Some More Features of Sphinx

Cross-referencing

Sphinx also supports extensive cross-referencing capabilities. One simple way to create references is to create a label before a heading with .. _some_reference:, and then reference it from any file using :ref:‘some_reference‘. References to external URLs are simple—we just use something like .. _some_reference: http://python.org to create the reference and :ref:‘some_reference‘ to use it. If we find ourselves using many external URL references, we may want to place all the external links into a single file and then add an .. include:: links.txt directive at the end of each documentation file.

Adding images

Another powerful feature is the ability to insert an image. This is done with the image directive. For example, if we keep the images in docs/source/img, the following directive inserts the file screenshot.png.

.. image:: img/screenshot.png
   :align: center

Finally, it is often useful to describe source code with the code directive.

.. code:: python
   list_comprehension = [ x*(x-1) for x in range(20) ]

It will render with syntax highlighting appropriate to the language.

The default appearance of the Sphinx documentation is straightforward and clean. Many other options exist. To use them, we have to alter the line html_theme = ’alabaster’ in conf.py by replacing alabaster with one of the following: classic, sphinxdoc, scrolls, agogo, traditional, nature, haiku, pyramid, or bizstyle. We can see screenshots of the various styles in the Sphinx online documentation. There is a lot more we can do with reStructured Text and Sphinx.

Do JavaScript documentation later

Sphinx was built to work with Python files. However, it is also possible to document other code by creating reStructured Text files to be compiled into the documentation. This provides a good way to keep the documentation together. At the moment, however, the methods to automatically extract documentation from JavaScript files with which to populate the Sphinx documentation remain limited. Since we will be using Storybook to document React components, it will make more sense to put the documentation into Storybook. We can then link the Sphinx and Storybook documentation pieces to combine it all into one, although the styles will remain different.