SPHINX Python documentation generator
Anna Ferrari - 29.06.2021 • Documentation of your python (an other languages like java, C++, R, PHP, javascript,….) code
• Outputs in HTML, Latex, ePub, https://www.sphinx-doc.org/en/master/ others
• Deploy on webpage (for example in ReadTheDocs) Python documentation https://docs.python.org/3/
• Python
• Linux kernel
• Conda
• Flask
• Matplotlib
• Jupiter Notebook
• Lasagne
• Indico
• Zenodo
…. Result at https://simpleble.readthedocs.io/en/latest/ Let’s get started ! https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html Create a new folder called simpleble-master
simpleble-master └── simpleble └── test.py test.py
def sum_two_numbers(a, b):
return a + b Add to test.py documentation: https://realpython.com/documenting-python-code/
def sum_two_numbers(a, b):
‘’’ This function add two numbers
Args: a (float) : first number to add
b (float) : second number to add
Returns: float
The sum of a and b
‘’‘ return a + b Install sphinx
ReadTheDocs Theme Create documentation root directory
Call sphinx quickstart to initialise the project
Let’s modify the confguration fle:
Uncomment
Add the theme for read the documents html_theme = "sphinx_rtd_theme"
Add the visualisation of the source code extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
html_show_sourcelink = True Build the html fle
Now we have an html fle, and if we double click we see it in the browser. It’s empty since we didn’t populated it yet.
Auto-generate .rst fle from python
youruser@yourpc:~yourWorkspacePath/simpleble-master/docs$ sphinx-apidoc -o ./source ../simpleble Let’s have a look into the index.rst
.rst means reStructuredText markup language Let’s create an introduction.rst and example.rst fles
Let’s see the result !
clean Auto-generate .rst fle from python
Create a folder in source names simpleble2
youruser@yourpc:~yourWorkspacePath/simpleble-master/docs$ sphinx-apidoc -o ./source ../simpleble
youruser@yourpc:~yourWorkspacePath/simpleble-master/docs$ sphinx-apidoc -o ./source/simpleble ../simpleble
2 2 Populate with introduction.rst and example.rst fles
2
Let’s see the result !
clean Publish the documentation in ReadTheDocs
You need to push the directory to your GitHub\GitLab repository
Create an account on https://readthedocs.org/
Follow instruction here: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/read-the-docs.html