Using Sphinx to Make Web Pages

For the sake of the super short tutorial, the brief introduction to restructured text is the first page of the web display and this current document is the second page.

Start Sphinx

Back to the console with the directory with your perfectDocument.rst (for me that’s a /dat/work/doc directory with the superShort.txt and now started Sphinx.txt).

To start sphinx, write:

sphinx-quickstart

You will need to answer a series of questions. If you do not know what to use, just accept the defaults with one exception - say yes to autodoc question. I don’t know any of the “right” answers. For consistency I picked up suggestion from the first author I read and use it (so sorry, forgot your name - my memory is “volatile”. Old age is a b. pain, but the alternatives are no more attractive...)

A bit of googling revealed that the author was Andrew Carter and the web address of his effort is:

http://packages.python.org/an_example_pypi_project/sphinx.html

Answers to sphinx-quickstart

Here is a partial list of questions and answers to sphinx-quickstart:

> Root path for the documentation [.]:  <ENTER>
> Separate source and build directories (y/N) [n]:  y
> Name prefix for templates and static dir [_]:  <ENTER>
> Project name:  an_example_pypi_project
> Author name(s):  Andrew Carter
> Project version:  0.0.1
> Project release [0.0.1]:  <ENTER>
> Source file suffix [.rst]:  <ENTER>
> Name of your master document (without suffix) [index]:  <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]:  y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:  n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:  y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]:  n
> coverage: checks for documentation coverage (y/N) [n]:  n
> pngmath: include math, rendered as PNG images (y/N) [n]:  n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:  n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:  y
> Create Makefile? (Y/n) [y]:  y
> Create Windows command file? (Y/n) [y]:  n

I will have a quick look at this file and return back to the sphinx-quickstart and answer all those questions as promised.

What is Left by quickstart?

A look at the doc directory reveals a number of directories and files that the sphinx-quickstart has created. In the source directory just under the doc directory that I created in my data partition /dat (full path of source is /dat/work/doc/source/) there is a small file index.rst. I remove everything from it, except the directive toctree, so that it now looks as follows:

.. toctree::
    :maxdepth: 2

My first web representation of this project will consist of two parts: superShort.rst and Sphinx.rst. So I copy those two files into the source directory and edit index.rst as follows:

.. toctree::
    :maxdepth: 2
.
    superShort
    Sphinx

Actually, I have cheated by adding a dot on the empty line, because I wanted all of index.rst to stay in one display box. Pity, but I do not know how to better show this manipulation of restructuredText in reStructuredText, nor do I want to go to the trouble to do it. Sorry! The important thing is that s in superShort must line up with : in :maxdepth, there needs to be a blank between :maxdepth and superShort. Also, sometimes I did not get index.rst at all. Probably because of my own mistakes, yet may be not. Does not matter much as it can be edited.

Making html

Now we will go beck to doc directory and issue the command:

make html

If that does not work, we will repeat the following several times after appropriate tuning:

make clean
make html

Finally, when make html causes the following message:

Build finished. The HTML pages are in build/html.
ak@supremo:/dat/work/doc$

We can open with Firefox a file index.html in doc/build/html directory. It remains to upload all this to the web, which is the topic for the next section.

Making the Web Page

Once the index.html is ready with all that its links refer to, the time is to upload it all to a web site. This is so simple that it is hardly worth talking about - upload all files from html directory:

doc/build/html/*

and also make _static subdirectory in the web page and copy all the contents of doc/build/html/_static/ into it. That’s it - point the browser to it and you have a web page. It is not perfect, but quite usable:

http://akabaila.pcug.org.au/sphinxTut/index.html

We are done with the web page!

Algis Kabaila 2011-08-05