Python Automated Documentation

If you are fastidious in writing proper Python documentation then you may be looking for a way to generate nice HTML documentation. I use sphinx for this.

After creating your “conf.py”, which I will assume is in a directory called “docs”. Execute the following from your source directory:

sphinx-apidoc -f -o .\docs\ .

This will automatically generate the .rst files, but not index.rst.

Your index.rst should look something like this:

NewsScraper Documentation
=====================

Independent Study files for analyzing the sourcing of news articles

.. toctree::
 :maxdepth: 2
 :caption: Contents:
 
 Main Driver <app.rst>
 Scrapers <Scrapers.rst>
 Parsers <Parsers.rst>
 Router <Router.rst>
 API <API.rst>
 Article Class <Article.rst>


Indices and tables
==================
.. toctree::
 :maxdepth: 2

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

You will need to set the display name and rst files for each module manually.

Next, run this to generate the HTML documentation:

sphinx-build -b html .\docs\ .\docs\build\

This will put the HTML in docs/build.