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. 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 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