I recently was introduced to the Sphinx package for automated code documentation. It is a slick tool for generating docs in multiple formats, including HTML, latex, and pdf. In this blog post, I will go through Sphinx’s procedure on my package SimpleDenseGruobi.
First, we should install the package.
pip install sphinx
Next, we need to open a terminal and cd to your documents folder (If you don’t have one like me, you can make one and then go there). After that is done, we need to use the following command in the terminal.
sphinx-quickstart
This command takes you thru the standard procedure of generating the documentation. However, you are not done. All you have is the machinery to make your document and not your actual documentation! If you do not want to go thru the tedium of generating the document templates, you can use the sphinx-autodoc extension. To do so, you need to run the following command (while still cd’ed to your documents folder). The second file path in this the relative path to your project source code.
sphinx-apidoc -f -o ./ ../
This generates the .rst files that are generated for you. All there is to do is include this file in the table of contents in the index.rst that Sphinx originally generated. This can be done by editing the file to include simple_gurobi.rst.
Welcome to SimpleDenseGurobi's documentation!
=============================================
.. toctree::
:maxdepth: 2
:caption: API:
simple_gurobi
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
We are technically done with the fiddly bits, but I honestly hate how the default webpage looks. It doesn’t read well at ALL. Luckily we can tinker with a few things to make it much better on the eyes. We will first need to install another package; this will give us the theme of ReadTheDocs.
pip install sphinx_rtd_theme
Then we need to edit the conf.py file to have the following sections.
# import the new package
import sphinx_rtd_theme
# edit extendsions to include the new theme
extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme', ]
# change the html export theme
html_theme = 'sphinx_rtd_theme'
We need to use the following two commands to make the docs in pdf and HTML format. At the time of writing, this process what very poorly documented, and I hope that this post helps someone else out. Shout out to my friend Gibs for introducing me to Sphinx.
make html
make latexpdf