Sphinx Cheat Sheet

Wherein I show by example how to do some things in Sphinx (you can see a literal version of this file below in This file)

Making a list

It is easy to make lists in rest

Bullet points

This is a subsection making bullet points

• point A

• point B

• point C

Enumerated points

This is a subsection making numbered points

1. point A

2. point B

3. point C

Making a table

This shows you how to make a table – if you only want to make a list see Making a list.

Name	Age
John D Hunter	40
Cast of Thousands	41
And Still More	42

Making links

Cross-references sections and documents

Use reST labels to cross-reference sections and other documents. The mechanism for referencing another reST document or a subsection in any document, including within a document are identical. Place a reference label above the section heading, like this:

.. _sphinx_helpers:

====================
 Sphinx Cheat Sheet
====================

Note the blank line between the reference label and the section heading is important!

Then refer to the reference label in another document like this:

:ref:`sphinx_helpers`

The reference is replaced with the section title when Sphinx builds the document while maintaining the linking mechanism. For example, the above reference will appear as Sphinx Cheat Sheet. As the documentation grows there are many references to keep track of.

For documents, please use a reference label that matches the file name. For sections, please try and make the reference label something meaningful and try to keep abbreviations limited. Along these lines, we are using underscores for multiple-word reference labels instead of hyphens.

Sphinx documentation on Cross-referencing arbitrary locations has more details.

External links

For external links you are likely to use only once, simple include the like in the text. This link to google was made like this:

`google <http://www.google.com>`_

For external links you will reference frequently, we have created a links_names.txt file. These links can then be used throughout the documentation. Links in the links_names.txt file are created using the reST reference syntax:

.. _targetname: http://www.external_website.org

To refer to the reference in a separate reST file, include the links_names.txt file and refer to the link through it’s target name. For example, put this include at the bottom of your reST document:

.. include:: ../links_names.txt

and refer to the hyperlink target:

blah blah blah targetname_ more blah

Links to classes, modules and functions

You can also reference classes, modules, functions, etc that are documented using the sphinx autodoc facilities. For example, see the module matplotlib.backend_bases documentation, or the class LocationEvent, or the method mpl_connect().

ipython sessions

Michael Droettboom contributed a sphinx extension which does pygments syntax highlighting on ipython sessions

In [69]: lines = plot([1,2,3])

In [70]: setp(lines)
  alpha: float
  animated: [True | False]
  antialiased or aa: [True | False]
  ...snip

This support is included in this template, but will also be included in a future version of Pygments by default.

Formatting text

You use inline markup to make text italics, bold, or monotype.

You can represent code blocks fairly easily:

import numpy as np
x = np.random.rand(12)

Or literally include code:

# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
# vi: set ft=python sts=4 ts=4 sw=4 et:
import matplotlib.pyplot as plt

plt.plot([1,2,3], [4,5,6])
plt.ylabel('some more numbers')

Using math

In sphinx you can include inline math \(x\leftarrow y\ x\forall y\ x-y\) or display math

\[W^{3\beta}_{\delta_1 \rho_1 \sigma_2} = U^{3\beta}_{\delta_1 \rho_1} + \frac{1}{8 \pi 2} \int^{\alpha_2}_{\alpha_2} d \alpha^\prime_2 \left[\frac{ U^{2\beta}_{\delta_1 \rho_1} - \alpha^\prime_2U^{1\beta}_{\rho_1 \sigma_2} }{U^{0\beta}_{\rho_1 \sigma_2}}\right]\]

This documentation framework includes a Sphinx extension, sphinxext/mathmpl.py, that uses matplotlib to render math equations when generating HTML, and LaTeX itself when generating a PDF. This can be useful on systems that have matplotlib, but not LaTeX, installed. To use it, add mathpng to the list of extensions in conf.py.

Current SVN versions of Sphinx now include built-in support for math. There are two flavors:

• pngmath: uses dvipng to render the equation

• jsmath: renders the math in the browser using Javascript

To use these extensions instead, add sphinx.ext.pngmath or sphinx.ext.jsmath to the list of extensions in conf.py.

All three of these options for math are designed to behave in the same way.

Inserting matplotlib plots

Inserting automatically-generated plots is easy. Simply put the script to generate the plot in any directory you want, and refer to it using the plot directive. All paths are considered relative to the top-level of the documentation tree. To include the source code for the plot in the document, pass the include-source parameter:

.. plot:: devel/guidelines/elegant.py
   :include-source:

In the HTML version of the document, the plot includes links to the original source code, a high-resolution PNG and a PDF. In the PDF version of the document, the plot is included as a scalable PDF.

# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
# vi: set ft=python sts=4 ts=4 sw=4 et:
import matplotlib.pyplot as plt

plt.plot([1,2,3], [4,5,6])
plt.ylabel('some more numbers')

(Source code, png, hires.png, pdf)

Emacs helpers

See ReST mode

Inheritance diagrams

Inheritance diagrams can be inserted directly into the document by providing a list of class or module names to the inheritance-diagram directive.

For example:

.. inheritance-diagram:: codecs

produces:

This file

.. _sphinx_helpers:

====================
 Sphinx Cheat Sheet
====================

Wherein I show by example how to do some things in Sphinx (you can see
a literal version of this file below in :ref:`sphinx_literal`)


.. _making_a_list:

Making a list
-------------

It is easy to make lists in rest

Bullet points
^^^^^^^^^^^^^

This is a subsection making bullet points

* point A

* point B

* point C


Enumerated points
^^^^^^^^^^^^^^^^^

This is a subsection making numbered points

#. point A

#. point B

#. point C


.. _making_a_table:

Making a table
--------------

This shows you how to make a table -- if you only want to make a list
see :ref:`making_a_list`.

==================   ============
Name                 Age
==================   ============
John D Hunter        40
Cast of Thousands    41
And Still More       42
==================   ============

.. _making_links:

Making links
------------

Cross-references sections and documents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use reST labels to cross-reference sections and other documents. The
mechanism for referencing another reST document or a subsection in any
document, including within a document are identical. Place a
*reference label* above the section heading, like this::

	.. _sphinx_helpers:

	====================
	 Sphinx Cheat Sheet
	====================

Note the blank line between the *reference label* and the section
heading is important!

Then refer to the *reference label* in another
document like this::

     :ref:`sphinx_helpers`

The reference is replaced with the section title when Sphinx builds
the document while maintaining the linking mechanism.  For example,
the above reference will appear as :ref:`sphinx_helpers`.  As the
documentation grows there are many references to keep track of.

For documents, please use a *reference label* that matches the file
name.  For sections, please try and make the *reference label* something
meaningful and try to keep abbreviations limited.  Along these lines,
we are using *underscores* for multiple-word *reference labels*
instead of hyphens.

Sphinx documentation on `Cross-referencing arbitrary locations
<http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
has more details.

External links
^^^^^^^^^^^^^^

For external links you are likely to use only once, simple include the
like in the text.  This link to `google <http://www.google.com>`_ was
made like this::

     `google <http://www.google.com>`_

For external links you will reference frequently, we have created a
``links_names.txt`` file.  These links can then be used throughout the
documentation.  Links in the ``links_names.txt`` file are created
using the `reST reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets>`_
syntax::

	.. _targetname: http://www.external_website.org

To refer to the reference in a separate reST file, include the
``links_names.txt`` file and refer to the link through it's target
name.  For example, put this include at the bottom of your reST
document::

     .. include:: ../links_names.txt

and refer to the hyperlink target::

    blah blah blah targetname_ more blah



Links to classes, modules and functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can also reference classes, modules, functions, etc that are
documented using the sphinx `autodoc
<http://sphinx.pocoo.org/ext/autodoc.html>`_ facilities.  For example,
see the module :mod:`matplotlib.backend_bases` documentation, or the
class :class:`~matplotlib.backend_bases.LocationEvent`, or the method
:meth:`~matplotlib.backend_bases.FigureCanvasBase.mpl_connect`.

.. _ipython_highlighting:

ipython sessions
----------------

Michael Droettboom contributed a sphinx extension which does pygments
syntax highlighting on ipython sessions

.. sourcecode:: ipython

    In [69]: lines = plot([1,2,3])

    In [70]: setp(lines)
      alpha: float
      animated: [True | False]
      antialiased or aa: [True | False]
      ...snip

This support is included in this template, but will also be included
in a future version of Pygments by default.

.. _formatting_text:

Formatting text
---------------

You use inline markup to make text *italics*, **bold**, or ``monotype``.

You can represent code blocks fairly easily::

   import numpy as np
   x = np.random.rand(12)

Or literally include code:

.. literalinclude:: elegant.py


.. _using_math:

Using math
----------

In sphinx you can include inline math :math:`x\leftarrow y\ x\forall
y\ x-y` or display math

.. math::

  W^{3\beta}_{\delta_1 \rho_1 \sigma_2} = U^{3\beta}_{\delta_1 \rho_1} + \frac{1}{8 \pi 2} \int^{\alpha_2}_{\alpha_2} d \alpha^\prime_2 \left[\frac{ U^{2\beta}_{\delta_1 \rho_1} - \alpha^\prime_2U^{1\beta}_{\rho_1 \sigma_2} }{U^{0\beta}_{\rho_1 \sigma_2}}\right]

This documentation framework includes a Sphinx extension,
:file:`sphinxext/mathmpl.py`, that uses matplotlib to render math
equations when generating HTML, and LaTeX itself when generating a
PDF.  This can be useful on systems that have matplotlib, but not
LaTeX, installed.  To use it, add ``mathpng`` to the list of
extensions in :file:`conf.py`.

Current SVN versions of Sphinx now include built-in support for math.
There are two flavors:

  - pngmath: uses dvipng to render the equation

  - jsmath: renders the math in the browser using Javascript

To use these extensions instead, add ``sphinx.ext.pngmath`` or
``sphinx.ext.jsmath`` to the list of extensions in :file:`conf.py`.

All three of these options for math are designed to behave in the same
way.

Inserting matplotlib plots
--------------------------

Inserting automatically-generated plots is easy.  Simply put the script to
generate the plot in any directory you want, and refer to it using the ``plot``
directive.  All paths are considered relative to the top-level of the
documentation tree.  To include the source code for the plot in the document,
pass the ``include-source`` parameter::

  .. plot:: devel/guidelines/elegant.py
     :include-source:

In the HTML version of the document, the plot includes links to the
original source code, a high-resolution PNG and a PDF.  In the PDF
version of the document, the plot is included as a scalable PDF.

.. plot:: devel/guidelines/elegant.py
   :include-source:

Emacs helpers
-------------

See :ref:`rst_emacs`

Inheritance diagrams
--------------------

Inheritance diagrams can be inserted directly into the document by
providing a list of class or module names to the
``inheritance-diagram`` directive.

For example::

  .. inheritance-diagram:: codecs

produces:

.. inheritance-diagram:: codecs

.. _sphinx_literal:

This file
---------

.. literalinclude:: sphinx_helpers.rst