Python Documentation Generator
Total Page：16
File Type：pdf, Size：1020Kb
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 configuration file: 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 file Now we have an html file, and if we double click we see it in the browser. It’s empty since we didn’t populated it yet. Auto-generate .rst file 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 files Let’s see the result ! clean Auto-generate .rst file 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 files 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.