Right Presentation

Set the Theme

The default html theme for reST is somewhat lacking. The following console command, from within the project folder, will switch to the Sphinxdoc theme:

sed -i "s/html_theme = 'default'/html_theme = 'sphinxdoc'/" ./conf.py

Modify the CSS

After html pages are built the first time, the CSS for the theme can be modified for specific purposes. For example, let’s disable the Sphinxdoc 80 pixel left and right margins.

To create an override copy of the CSS which you can modify, enter the following console commands from within the project folder:

cp _build/html/_static/sphinxdoc.css _static/
touch _static/.gitignore

Note

The main .gitignore file could list *static and *_static, which would prevent git from tracking changes to the CSS. Adding a blank .gitignore with the touch command fixes this problem.

You might prefer to edit this file interactively with nano, although you can comment out the margin command using sed:

sed -i "s/  margin: 0px 80px 0px 80px/# margin: 0px 80px 0px 80px/" ./_static/sphinxdoc.css

Make index.rst Better

Most of us do not start reading a book by staring at the Table of Contents, and most websites are made up of multiple pages or documents. The ability to hyperlink information so that it is accessible and understandable without referring to an index is a feature of the web. With this thought, the initial page index.html can be replaced with something better as follows.

Above the page heading of each document page, add a reference label:

.. _labelname:

Then edit the document index.rst in the project, and write the content for the front page. Embed :ref: links in the text to connect the site pages from the rewritten front page index. This approach is demonstrated in the revised index for this guide.

If your main documents are numbered, a Table of Contents can be generated by:

Table of Contents:
====================

.. toctree::
   :maxdepth: 2
   :glob:

   [0-9]*

Borrow from Others

This GitHub repository shows that the idea of publishing Sphinx documents in gh-pages has occurred to others. I like the elegant way that this project is presented: the project writes the project README.rst file, which is the project documentation as a Sphinxdoc.

Other example websites demonstrate the power of reStructuredText as a documentation and web development tool. Most of these sites have Show Source links to the original text of the pages.