Debugging sphinx documentation

After writing some documentation in a ReStructured Text (.rst) file, the next step is to run "make html" or "make latex" to build this documentation. The Sphinx build system likes to generate warning messages. Even though a warning is not an error, a warning should be fixed because it signals that there could be an error in the documentation markup. In my experience, fixing warnings generated by Sphinx can be a somewhat tricky. First off, the messages are somewhat cryptic. If you can't figure out what the warning refers to, go to the Sphinx documentation page (http://sphinx.pocoo.org/contents.html) and search around for the term that appears in the warning. A good place to start is the "reStructuredText Primer".

In order to create a documentation page that consists of several smaller pages linked together, use the ".. include:" directive to include all the smaller files. Sphinx will complain that it can't locate these smaller files in any of the table of contents. This is why you ALSO need to create at the top of the page

.. toctree::
   :hidden:

And then list all the smaller files in the hidden table of contents. That will stop Sphinx from complaining.