5.9. Sphinx

Using Sphinx to create documentation.

5.9.1. Installing Sphinx

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

# Ensure you are in the project folder with the virtualenv activated
pip install sphinx
sphinx-quickstart
pip install sphinx-notfound-page
pip install --upgrade myst-parser

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

Add the following to extensions:

extensions = [
  "notfound.extension",
  "myst_parser"
]

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

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

myst_heading_anchors = 3

The heading anchors allows internal cross referencing with markdown.

Sphinx not found extention Markdown compatibility Markdown cross referencing

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

This is information from when I decided to write the documents in ReStructuredText but I have since decided to try migrating to markdown.

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`_ recommends saving files as .txt rather than .rst for compatibility.

.. _Read the docs: http://documentation-style-guide-sphinx.readthedocs.org/en/latest/style-guide.html

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.

.. code-block:: python

import this

Example website_ can be referenced:

  .. target-notes::

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

.. target-notes::

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

.. seealso:: ``.. seealso::`` This is a simple **seealso** note.

.. note:: ``.. note::`` This is a **note** box.

Warning box:

  .. warning:: Remember the space between the directive and the text

.. warning:: ``.. warning::`` Remember the space between the directive and the text

.. image:: ../photoshop/_static/cat-in-hat.jpg
    :width: 200px
    :align: center
    :alt: alternate text