Simple four steps to get the HTML files from your python codeYou just need four steps.
- Execute sphinx_quickstart, and make sure that you check autodoc mode on:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
- In conf.py, add the path to your source code:
sphinx-apidoc -o . ../src/
Include reST documents into index
Topic and commentstopic directive creates
tag in HTML. It seems to be pretty useful in describing what the reST document does.
.. topic:: What is Sphinx and the RST syntax ? CONTENTS ...When you just use two dots, it works as a comment.
toctreeWhen you open the index.html, you will see nothing in the contents. It is because there is nothing under the
toctreedirective. Open the index.rst file which is the main reST for your project. You need to add the modules.
.. toctree:: :maxdepth: 2 hello1You may not want to show toctree. This will notify Sphinx of the document hierarchy, but skip inserting links into the document.
.. toctree:: :hidden:You can make toctree numbered with
.. toctree:: :maxdepth: 1 :numbered:
:doc:`…`In this case, you can explicitly include the reST document with
:doc:`hello1` Instructions on how to get the distribution.
API documentationIn step3, we can get (semi) automatically generated API documentation file from Sphinx with
sphinx-apidoc command. Whenever you want to add more documentation to it, you have to do it
Including math in the documentationAdd
'sphinx.ext.pngmath'in the extensions list. Then, use math directive or field::math:`a^2 + b^2 = c^2`. .. math:: (a + b)^2 = a^2 + 2ab + b^2 (a - b)^2 = a^2 - 2ab + b^2You need to specify the latex location in your computer.
sphinx-build -b html -D pngmath_latex=`which latex` . _build/html.
Useful Sphinx knowledge
conf.py, you can add more Sphinx features with extensions list.extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.viewcode','sphinx.ext.todo']