Sphinx

Sphinx is a a documentation builder that creates html documents from Restructured text.

Installing Sphinx

1. Install

    pip install -U Sphinx
   

2. To use markdown with Sphinx

    sudo pip install recommonmark
   

Start a Sphinx project

1. Navigate to your docs directory and enter:

    sphinx-quickstart
   

   Sphinx will then run through the questions it needs a to create the project.

2. To use the ReadTheDocs theme, in conf.py in your source directory:

    html_theme = "sphinx_rtd_theme"
   

3. To use markdown

    source_suffix = ['.rst', '.md']
    source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser',}
   

4. To remove blank pages from LaTeX documents: in conf.py:

    latex_elements = { 'classoptions': ',openany,oneside'}
   

To use figure numbers

1. Add the following to conf.py:

    numfig = True
   

2. A figure element should look like:

    .. figure:: /images/simple_modern_acol.png
       :scale: 30
       :alt: Convention Card
       :figclass: align-center
       :name: simple_modern_acol
   
       Convention Card
   

3. Any reference to the figure should take the form:

    (See :numref:`simple_modern_acol` A sample convention card)
   

To use markdown

See Sphinx pages

1. In terminal

    pip install --upgrade recommonmark
   

2. in conf.py

    from recommonmark.parser import CommonMarkParser
    ...
    extensions = ['recommonmark']
    ...
    source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser',}
    source_suffix = {
        '.rst': 'restructuredtext',
        '.txt': 'markdown',
        '.md': 'markdown',
    }