Feb. 5, 2023
Documenting Python projects
More on:
Go back
Python projects like Django, scikit-learn, and pandas, use Sphinx to create the documentation. Sphinx is a documentation generator that was developed to document Python itself.
It reads reStructuredText files and converts them to HTML, LaTeX, plain text and others. You write the reStructuredText files as the inputs for the generator.
reStructuredText is a markup language, which consists of instructions on a text document that formats the presentation. In other words, it tells the generator how the final text page should look like. HTML is the language used to display documents on a web browser. Please see fig. 1 to see examples from the Sphinx' website.
Once you install Sphinx, running just one command, a skeleton of the documentation is created for you. The documentation is created in a hierarchical way (like a tree). You then need to add more instructions to the created files, but you don’t start from scratch.
A theme to modify the front-end can be used (the colors and the “feel” of the document). There are themes already available with the library, or you can use third-party ones. Please see fig. 2 to see some of the default themes, also from the official website.
To control the front-end or appearance, you need to create the templates. A template is a pattern file that combines HTML instructions, and can use stylesheets and variables. These are very similar to Django templates and its inheritance principle. The default language for the templates is Jinja.
If your Python modules or functions have docstrings, they can be added to the documentation using extensions. Docstrings are used to explain how to use your functions. If you change the docstrings, they get updated on the documentation.
The code snippets in your docstrings can also be tested using extensions (third-party libraries).
A library to test the documentation is doctest. The library pytest can add functionalities to doctest.
The link to Sphinx: Sphinx
A good way to get started: Tutorial
Bonus info: Sphinx is a mythical creature with human head, lion body and wings.
It reads reStructuredText files and converts them to HTML, LaTeX, plain text and others. You write the reStructuredText files as the inputs for the generator.
reStructuredText is a markup language, which consists of instructions on a text document that formats the presentation. In other words, it tells the generator how the final text page should look like. HTML is the language used to display documents on a web browser. Please see fig. 1 to see examples from the Sphinx' website.
Once you install Sphinx, running just one command, a skeleton of the documentation is created for you. The documentation is created in a hierarchical way (like a tree). You then need to add more instructions to the created files, but you don’t start from scratch.
A theme to modify the front-end can be used (the colors and the “feel” of the document). There are themes already available with the library, or you can use third-party ones. Please see fig. 2 to see some of the default themes, also from the official website.
To control the front-end or appearance, you need to create the templates. A template is a pattern file that combines HTML instructions, and can use stylesheets and variables. These are very similar to Django templates and its inheritance principle. The default language for the templates is Jinja.
If your Python modules or functions have docstrings, they can be added to the documentation using extensions. Docstrings are used to explain how to use your functions. If you change the docstrings, they get updated on the documentation.
The code snippets in your docstrings can also be tested using extensions (third-party libraries).
A library to test the documentation is doctest. The library pytest can add functionalities to doctest.
The link to Sphinx: Sphinx
A good way to get started: Tutorial
Bonus info: Sphinx is a mythical creature with human head, lion body and wings.
