-
Notifications
You must be signed in to change notification settings - Fork 685
reStructuredText & Sphinx Cheat Sheet
Nathan Dyer edited this page Nov 8, 2022
·
2 revisions
*Italic text*
**Bold text**
``Inline Code``
:sup:`Super Script`
:sub:`Sub Script`
* Unordered item
* Unordered item
1. Nested ordered item
2. Nested ordered item
a. Nested ordered item
* Unordered item
First term
This is the definition for the first term.
Note that it can span multiple lines, and is indented.
Second term
The second term is defined.
.. This is a single line comment
Note that comments can span multiple lines.
Below is a literal block of code::
Note the special :: character above, and that this code is indented.
.. image:: image.png
:height: 100px
:width: 100px
:align: bottom
:target: target_
Figures are images that also include captions:
.. figure:: image.png
:alt: A beautiful sunrise
Above is a photo of the sunrise, taken by photographer John Smith.
===============
Level 1 Heading
===============
Level 2 Heading
---------------
Level 1 Heading
^^^^^^^^^^^^^^^
Level 2 Heading
+++++++++++++++
Notes about headings:
- Using an overline is optional
- The heading structure is determined simply by the order in which symbols are encountered
- For best results, use the following recommended characters: = - ` : . ' " ~ ^ _ * + #
.. _anchorbyref:
.. _Anchor link by text:
.. _External link name: http://example.com
.. [1] A footnote
.. [cit1] A global citation
`External link <http://example.com>`_
`External link name`_ or `Example <External link name_>`_
`Anchor link by text`_ or `Anchor <Anchor link by text_>`_
`Anchor link by ref <anchorbyref_>`_
:ref:`anchorbyref`
Reference a footnote using the notation [1]_
Reference a global citation like [cit1]_
Section Heading
---------------
`Link <Section Heading>`
============ ======== ========
Simple table Header 2 Header 3
============ ======== ========
Column 1 Column 2 Column 3
Horizontal column span ...
---------------------- --------
... ... ...
============ ======== ========
+----------+----------+----------+
| Grid | Header 2 | Header 3 |
| Table | | |
+==========+==========+==========+
| Column 1 | Column 2 | Vertical |
+----------+----------+ column |
| Horizontal span | span |
+----------+----------+----------+
You can also use CSV files to create simple tables, using the csv-table directive.
Directives contain a directive type, arguments, and options (depending on the type of directive)
.. container:: [container class]
.. csv-table:: [table title]
:header: CSV data for headers
:widths: number [, number]
:file:: filename
:encoding: encoding
:header-rows: number
:delim: character, "tab", or "space"
:quote: character
:escape: character
.. rubric:: [title]
.. toctree::
:maxdepth: number of title levels
:glob:
:hidden:
:numbered:
:caption: caption text
:titlesonly:
.. topic:: [title]
.. sidebar:: [title]
:subtitle: subtitle
.. admonition:: [title]
.. attention::
.. caution::
.. danger::
.. error::
.. hint::
.. important::
.. note::
.. tip::
.. warning::
.. seealso::
.. deprecated:: [version]
.. versionadded:: [version]
.. versionchanged:: [version]
.. math::
.. raw:: output format
.. highlight: language
:linenothreshold: number
.. codeblock: [language]
:lineos:
:emphasize-lines: number [, number]
:caption: caption text
:name: block target name
.. literalinclude: filename
:language: language
:emphasize-lines: number [, number]
:lineos:
:encoding: encoding
:diff: filename
:dedent: number
:any: `name`
:doc: `document name`
:download: `filename`
:envvar: `name`
:keyword: `python keyword`
:option: `CLI option`
:abbr: `long (abbreviation)`
:command: `name`
:kbd: `keystrokes`
:program: `program`
:pep: `number`
:rfc: `number`