Sphinx¶
Sphinx is a tool to build any kind of documenation.
Why shall we use it?¶
converts reStructuredText to an output format, i.e. html
creates links etc. within and amount documents
supports many customizations
native python documentation tool widely adapted
change documentation via git
Quick Start¶
If you want to add documenation to a project, please checkout this guide.
Example¶
Now you can start writing actual documentation. Each html page corresponds
to one .rst
file. So image we want to document a coffee machine.
Congrats for buying our new super awesome coffee-machine. Here we provide
more details on the following topics.
.. toctree::
:maxdepth: 2
:caption: Table of Content
safety
quickstart
This table of content will do three things:
- create links to the heading in
saftety.rst
andquickstart.rst
right there up to level 2
- create links to the heading in
create a navigation menu on the side
tell sphinx that these documents form a joint assemble
To complete the example we have the two missing files linked in the table of content.
Read everything very very carefully.
Safety
======
This coffee machine can only be installed by an electrician. If you do
otherwise, you loose all warranty.
Responsibility (level 1)
========================
We assure you that we don't take any responsibility. Never.
Exception (level 2)
___________________
No exceptions.
Exception (level 3)
*******************
Really?
So the last heading Exception (level 3)
will not appear in the table of
content of the index page. All other heading will.
Instructions
============
Follow the following steps:
#. Take the machine out of its box.
#. PLug the cable into the socket.
#. Switch it on.
Afterwards please take a look at the conf.py
file. This is the place to go
to when customizing your documentation.