Sphinx was written for the Python documentation and is used extensively in official document creation, though it can be used to create other documents as well. All of the documentation on the Python site is generated by Sphinx and most Python projects use it for their websites. Even the Sphinx website is written in reStructuredText (reST) and converted in to HTML.
PEP 287 proposes that reST markup should be used for structured text documentation within Python docstrings, PEPs, and other documents that require structured markup. Of course, plain text docstrings are not deprecated; reST simply provides more options for developers who want to be more expressive in their documentation.
Sphinx can convert reST into HTML, PDF, ePub, Texinfo, and man pages. The program is also extensible, providing plug-ins for generating mathematical notation from formulas or highlighting source code.
Sphinx can be installed in the normal ways: either through pip or downloading an installation package. Once installed, it is suggested to move (through the command prompt) to the project directory, as the program defaults to looking for files in the current directory. It's not necessary, as the path can be changed later; it just makes life easier.
Run the sphinx-quickstart command. The program will run through an interactive, text-based setup, which will ask the user multiple questions. The questions are generally self-explanatory, but be sure to check the Sphinx documentation if something doesn't make sense. Don't panic, however, if you just pick the defaults and you don't get the results expected. This process is simply creating the default configuration files, which can be manually modified later. A key thing to point out is, if you want to use your docstrings to generate your documenation, ensure you select autodoc for installation.
When completed, you should now see conf.py and index.rst in your project directory. These are used to allow Sphinx to operate. conf.py as the configuration file for Sphinx. It is the primary location for setting up Sphinx and the entries made during the quickstart process are stored here. index.rst is the primary file for telling Sphinx how to create the final documentation. It basically tells Sphinx what modules, classes, and so on to include in the documentation.
By default, conf.py looks for files in PYTHONPATH; if you are looking to use files in another location, make sure you set it up correctly at the top of the file. Specifically, uncomment import os, import sys and the sys.path.insert() line (and update the path as needed).
This is demonstrated in the following screenshot:
In the preceding screenshot, we have an example conf.py file for our fuel farm project. Only two of the component paths have been added for demonstrative purposes. In reality, you would want to add all of the paths that you want to include within the documentation.
If you set up conf.py to use autodoc (line 43 in the preceding screenshot), the next step is simple. Go to index.rst and tell Sphinx to automatically find the information for the documentation. The easiest way to do this is take a look at http://www.sphinx-doc.org/en/stable/ext/autodoc.html#module-sphinx.ext.autodoc, which explains how to automatically import all desired modules and retrieve the docstrings from them.
An example of automodule from autodoc is shown in following screenshot. If you go to the autodoc site, you'll see you can also use autoclass and autoexception to document individual components within a Python program, if you don't want or need to document an entire module. There are also a large number of options and advanced features available, which are beyond the scope of this book. The following screenshot shows the index.rst file:
The preceding screenshot shows an example for this project. Everything apart from the two automodule sections is default information, automatically created by Sphinx. The automodule sections tell Sphinx what the name is of the Python module to import: the Python filename without the .py extension. The other parts of the file are described as follows:
- members: This automatically gathers documentation for all public classes, methods, and functions that have docstrings. If you don't use it, only the docstring for the main object (a module, in this case) will be imported.
- undoc-members: This does the same thing, except it will get objects that don't have docstrings. Obviously, the information for these items will be limited compared to a docstring.
- show-inheritance: This specifies that the inheritance tree for the module will be included. Needless to say, if you aren't using inheritance, this won't do much good.
Once conf.py and index.rst are updated, run the make html command to generate the HTML files for the project. It is not unusual to receive errors, particularly Sphinx telling you it can't find a particular module. This usually means you provided the wrong path in conf.py.
One unusual error you can receive is shown in the following screenshot:
This error indicates that Sphinx is unable to proceed because it found an invalid character. If you look at the utility_formulas.py file, there is nothing on line 17 that would cause the error. However, if you check line 15, you'll see that we included a percentage symbol.
Rather than removing the symbol, if we modify utility_formulas.py to include line 2 in the following screenshot, that will remove the Sphinx error:
When Sphinx runs correctly, you should see something like the following screenshot:
If you go into the project directory, you should find index.html in the _build/html directory (assuming you used the default values).
When you open it, you should see something like following screenshot. Currently, this output only shows the information in the docstrings, but reST allows you to create much more useful information, such as explaining how to use the software.
If you don't like the default theme, there are a number of other themes included with Sphinx. Obviously, being HTML, you can make your own as well. The following screenshot shows the Sphinx output:
