REST reStructuredText notes (see also Sphinx notes)
SEE CHEATSHEET AT END
file1.rst --------- Contents: .. toctree:: :maxdepth: 2 keys api Go read :ref:`morestuff` for more. Read about python package :py:mod:`package.name` and python function :py:func:`package.name.function`. The python class :py:class:`package.name.ClassName` might also be useful, and its method :py:meth:`package.name.ClassName.method`. Not to mention the attribute :py:attr:`package.name.ClassName.attrname`. The code might throw the exception :py:exc:`package.name.MyException`. file2.rst --------- .. _morestuff: More stuff ========== To show code:: Indent this 4 spaces. You can indent more or less. And keep going. Even include blank lines It ends after a blank line and returning to the original indentation. You can also markup ``short inline code`` like this.
Automatically include the doc for a class like this:
.. _api: .. autoclass:: healthvaultlib.healthvault.HealthVaultConn :members:
And document them:
class MyClassName(object): """ Description. Can refer to :py:meth:`.method1` here or anywhere in the file. :param string parm1: His name :param long parm2: His number """ def __init__(self, parm1, parm2): pass def method1(self, arg1, arg2): """ Description :param unicode arg1: something :param object arg2: something else """
Various code blocks:
.. code-block:: bash|python|text :linenos: :emphasize-lines: 1,3-5 # Hi # there # all # you # coders # rejoice
1# Hi 2# there 3# all 4# you 5# coders 6# rejoice
You can include an
`HTML link`_ like this
and the definition can go nearby or at the bottom of the page:
.. _HTML link: http://foo.bar.com/
Or you can just write
`HTML link <http://foo.bar.com>`_
all in one place.
Link to a filename in this set of docs using
:doc:`Any text you want </path/to/page>`
Don’t include the “.rst” on the end of the filename. Relative filenames work too. But it’s better to use :ref:, see next.
You can define an anchor point, which Sphinx calls a label. Put this above a section header:
.. _my-label: My Section ----------
Now from somewhere else, you can write
and it’ll be rendered as “My Section” and will link to the
section. If you want some other text in the link, you
:ref:`any text <my-label>` instead.
Copied from https://sphinx-tutorial.readthedocs.io/cheatsheet/ - thanks to Read The Docs.