Simple Sphinx Tutorial

Introduction & Disclaimer

After doing a good bit of coding on the new project that I’m working on, I was eager to find something that could “autogenerate” documentation for me, so I didn’t have to keep doing docstring to README.md copy and pastes (and then added examples where I thought necessary). I took a look at Sphinx (and in fact, everywhere you look, people say “it’s the autogeneration documentation code of choice”).

Unfortunately, IMOP, the documentation goes from 0 to 50,000 ft in no time flat (and you don’t know .rst which I didn’t, it seems like you’re a supporting cast member in Gravity)), and lacks a simple step by step tutorial that allows you to get up and running (even the PyPi Project documentation fails to give detailed file structure and command line execution instructions to obtain the illustrated results, which are vital if you want this to work properly). After a 24 hour slug-fest and almost throwing my computer out the window, I got things up and running. As usual, I thought I should put together the “idiot’s tutorial” that I wish had existed when I was first trying to get this working… so here it is.

DISCLAIMER: I’m not an advanced Sphinx user (that’s kind of the point, right), so I glaze over a lot of the details because there are reams of content online about “the details”… this is just an easy, step by step process to get the autodoc working and the command lines that can get you there).

Tutorial

1. Go to your project file, which may have a structure like this:

   my_project/
       __init__.py
       my_project/
           __init__.py
           some_funs.py
           other_funs.py
   

   and create a docs folder in the uppermost tree with a my_file.rst, so your doc structure is now (I’ll go over the my_file.rst next)

     my_project/
         __init__.py
         docs/
             my_file.rst
         my_project/
             __init__.py
             some_funs.py
             other_funs.py
   

   run the following to do a sphinx-quickstart.

     $ cd docs/
     $ sphinx-quickstart
   

   Hit enter for all of these values (i.e. accept the default values) except for:

     > autodoc: automatically insert docstrings from modules (y/N) [n]: y
   
     > Create Makefile? (Y/n) [y]: y 
   

2. You should now have a file structure that looks like this:

   my_project/
       __init__.py
       docs/
           _build/
           _static/
           _templates/
           conf.py
           index.rst
           Makefile
           my_file.rst
       my_project/
           __init__.py
           some_funs.py
           other_funs.py
   

3. There are three changes you need to make now to get the project to autogenerate documentation for your python code:

   1. go into your my_file.rst (which is blank right now) and add the following lines:

      Name of my Project
      ****************
      
      .. automodule:: my_project.some_funs
          :members:
      
      .. automodule:: my_project.other_funs
          :members:
      

      NOTE: if you didn’t have a module.function sub-folder structure and only had a my_fun.py, the above would simply be ..automodule:: my_fun

   2. Then go into your index.rst file and make the following
      addition:

      Contents:
      
      .. toctree::
         :maxdepth: 2
      
         my_file
      

      NOTE there is not extension .rst added to my_file, this is intentional as some users use extension .txt and some use .rst so the quickstart is “extension agnostic.”

      This points your index.rst to your my_file to the autogenerate the documentation of the code. Also note that index.rst and my_file.rst are in the same folder (this is also key)

   3. Go into your conf.py file, and then add the following two
      lines:

      s = os.path.abspath('../')
      sys.path.append(s)
      

      This must be done, because the python project needs to be on your system path in order for sphinx-build to work. An alternative workaround here would be to append you $PYTHONPATH to include the project.

      Take note of the file structure.. I’m basically pointing the system path to the folder above the docs folder, which is the same location I could invoke the iPython interpreter to import the project’s functionality assuming that the project wasn’t already on the system path.

      I also personally change

      html_theme = 'sphinxdoc'
      

      because I don’t like the “default”.

   4. cd into the docs folder (if you’re not there already) and then enter from the command line:

      $ sphinx-build -b html ./ _build
      

      This tells Sphinx, look to the current directory for the .rst files and output the .html into _build.

After running the last command, you should now go into your _build folder and there will be .html files that show your autogenerated documentation, and you’re off to the races.