Sphinx
If you want to get familiar with Sphinx there's a quickstart tutorial online, but we'll walk through a basic conversion now. There's broadly three stages: 1) build a configuration python module and basic index page – the page isn't in HTML, but is instead in reStructuredText, a simple markup language in files with the extension .rst; 2) build the specific reStructuredText file describing the files you want to include; 3) build the HTML.
First, make yourself a docs directory, and copy docs.py into it. Open a command prompt in the directory, and enter:
sphinx-quickstart
You'll now be presented with a series of options; you can just push ENTER for all options except:
Project name: Docs
Author: Your name
Project version: 1
autodoc: automatically insert docstrings from modules (y/n) [n]: y
viewcode: include links to the source code of documented Python objects (y/n) [n]: y
Create Makefile? (y/n) [y]: n
Create Windows command file? (y/n) [y]: n
This will make an initial conf.py and index.rst. At the moment these don't contain anything
about your specific files. Open conf.py and add the following line after the imports:
sys.path.append('C:\filepath\directories')
Where C:\filepath\directories is the directory where your docs.py file is. Note there should be
no trailing slash at the end of the path.
Also change the line:
extensions = []
(Which may be split over two lines.)
To:
extensions = ['sphinx.ext.autodoc']
Now open index.rst and change it to:
.. toctree::
:maxdepth: 2
docs
Make sure the indents are spaces not tabs. This will make the next stage pick up your file.
Now build the reStructuredText framework for your file. Enter:
sphinx-apidoc -o . .
The two dots are to say that the output directory is the current one, as is the source directory. If you had your files in alternative directories
you'd have to adjust this (details of options; you might also have to move the index.rst into any source directory).
That should have built a few directories ready for the pages, plus some .rst files. As your conf.py file is currently in the same directory
as the docs.py, it will have thought that's a python file you want documenting and created a .rst file for it. Delete conf.rst. The edit
modules.rst to remove conf.
You can now build the webpages. Enter:
sphinx-build -c . -b html . _build
This will build the webpages in the _build directory. Again, the dots are for the current directory
(details of options).
If you want to add content other than the standard details, you can add reStructuredText anywhere in the .rst files produced in the second step, as long as you don't mess with the automatically produced code. Experiment to see where it ends up in the page.
Ok, that's understanding the documentation; let's look at solving a problem with it.