5.9. Sphinx

Using Sphinx to create documentation.

5.9.1. Installing Sphinx

Create a project folder and Virtualenv (remember to activate it) then:

# Ensure you are in the project folder with the virtualenv activated
pip install sphinx
sphinx-quickstart

You can usually accept the defaults unless you have something specific in mind.

Add the following to the conf.py file after extensions:

source_suffix = {
    '.txt': 'restructuredtext',
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

5.9.2. Using Sphinx

Create another page with the suffix .rst e.g.

touch sphinx.rst

Add information to the page, including a heading underlined by equals signs.

On the index.rst page leave a line space under maxdepth and add the file name. When the HTML files are generated, it will pick up the titles of the pages from the files you list there and create a contents page.

make html

5.9.3. Notes

Headings with a line above and below are optional - only the line below is required.

This is the heading structure I have settled on:

==========
Page title
==========

Heading 1
=========

Heading 2
---------

The other thing they have on each page at the top to help with linking is:

.. _page_name:

You can link to them with:

:ref:`page_name`

This will insert the title from the other page that is directly under the link marker.

More information can be found at http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#internal-and-external-links

`<http://www.python.org/>`_
OR
`Python <http://www.python.org/>`_

.. _rst_tutorial:
LETS YOU LINK USING
:ref:`rst_tutorial`

A paragraph with `a link`_.
Underneath the paragraph put:
.. _a link: http://example.com/

Code within a line can be highlighted:

Here is a ``specific`` word highlighted as code using double backticks.

Note

Read the docs [1] recommends saving files as .txt rather than .rst for compatibility.

Notes in a box can be added using:

.. note:: `Read the docs`_ recommends saving files as .txt rather than .rst for compatibility.
OR
.. note::

  `Read the docs`_ recommends saving files as .txt rather than .rst for compatibility.

import this

Example website [2] can be referenced:

.. target-notes::

.. _`Example website`: http://www.example.com/