Sphinx Style Guide¶

Headlines¶

Example:

###################
How To: Sphinx (h1)
###################

**************
Headlines (h2)
**************

Headline (h3)
=============

Headline (h4)
-------------

Headline (h5)
^^^^^^^^^^^^^

Headline (h6)
"""""""""""""

Result:

How To: Sphinx (h1)
Headlines (h2)
Headline (h3)
Headline (h4)
Headline (h5)
Headline (h6)

Styles¶

**Bold text**
*Italic text*
``Inline literal/code``
:sup:`super`\ Script
:sub:`sub`\ Script

Bold text
Italic text
Inline literal/code
superScript
subScript

Bullet Lists¶

* Unordered item
* Unordered item

    #. Nestes ordered item
    #. Nestes ordered item

        #. Nested ordered item

* Unordered item

Unordered item
Unordered item
1. Nestes ordered item
2. Nestes ordered item
  Nested ordered item
Unordered item

Targets and Links¶

.. Anchor target

.. _anchorbyref:
.. _Anchor link by text:

.. External target

.. _external_link_ref: https://example.com
.. _External link name: https://example.com

.. Footnote target

.. [1] footnote text

.. Citation target

.. [cit1] A global citation

.. External links

`External link <https://example.com>`_
`External link name`_
`Example Text <External link name>`_
`External link by ref <external_link_ref>`_

.. Internal links

`Anchor link by text`_
`Anchor <Anchor link by text>`_
`Anchor by ref <anchorbyref>`_
:ref:`Anchor <anchorbyref>`

.. Footnote

Reference a footnote [1]_

.. Citation

Reference a global citation [cit1]_

.. Section Link

Section Heading
===============
`Link <Section Heading>`_

[cit1]

A global citation

External link
External link name
Example Text
External link by ref

Anchor link by text
Anchor
Anchor by ref
Anchor

Reference a footnote [1]

Reference a global citation [cit1]

Section Heading¶

Link

Tables¶

+-----------------+-----------------+-----------------+
| Grid table      | Header 2        | Header 3        |
|                 |                 |                 |
+=================+=================+=================+
| Column 1        | Column 2        | Vertical        |
+-----------------+-----------------+ column          +
| Horizontal span                   | span            |
+-----------------+-----------------+-----------------+

============  ========  ========
Simple table  Header 2  Header 3
============  ========  ========
Column 1      Column 2  Column 3
Horizontal column span  ...
----------------------  --------
...           ...       ...
============  ========  ========

.. csv-table:: table title
    :header: "Header 1", "Header 2", "Header 3"
    :widths: 20, 20, 20
    :encoding: utf-8
    :header-rows: 1

    "Row 1, Column 1", "Row 1, Column 2", "Row 1, Column 3"
    "Row 2, Column 1", "Row 2, Column 2", "Row 2, Column 3"

The csv-table directive can be used to create tables from CSV files:

.. csv-table:: table title
    :header: "Header 1", "Header 2", "Header 3"
    :widths: 20, 20, 20
    :encoding: utf-8
    :header-rows: 1
    :file: table.csv

Grid table¶

Grid table	Header 2	Header 3
Column 1	Column 2	Vertical column span
Horizontal span		Vertical column span

Simple table¶

Simple table	Header 2	Header 3
Column 1	Column 2	Column 3
Horizontal column span		…
…	…	…

CSV table¶

table title¶
Header 1	Header 2	Header 3
Row 1, Column 1	Row 1, Column 2	Row 1, Column 3
Row 2, Column 1	Row 2, Column 2	Row 2, Column 3

Images and Figures¶

Figures are images with captions. They support all image options.

.. image:: image.png
    :alt: Image alt text
    :width: 150px
    :height: 150px
    :align: center
    :target: target_

.. figure:: image.png
    :align: center
    :height: 150px
    :name: figure-name

Figure caption :figure:`figure-name` or `Example <figure-name>`_

Image¶

Figure¶

Figure caption figure-name or Example

Comments¶

.. comment
    This is a comment

Directives¶

.. directive:: argument
    :option: value

    Directive content

Table of Contents¶

.. local table of contents. The ``:local:`` option is optional.

.. contents:: Table of Contents
    :local:
    :depth: 2

.. defines global structure and includes all sub toc-trees and tocs
    Can also be set to visible by omitting the ``:hidden:`` option

.. toc-tree:: Table of Contents
    :maxdepth: 2
    :numbered:
    :hidden:

    file.rst
    second_file
    directory/file

Table of Contents (this document)¶

Content Block Directives¶

`.. topic::` [title]¶

.. topic:: Topic title

    Topic content

`.. admonition::` [title]¶

.. admonition:: Admonition title

    Admonition content

Admonition title

Admonition content

`.. attention::`¶

.. attention::

    Attention content

Attention

Attention content

`.. caution::`¶

.. caution::

    Caution content

Caution

Caution content

`.. danger::`¶

.. danger::

    Danger content

Danger

Danger content

`.. error::`¶

.. error::

    Error content

Error

Error content

`.. hint::`¶

.. hint::

    Hint content

Hint

Hint content

`.. important::`¶

.. important::

    Important content

Important

Important content

`.. note::`¶

.. note::

    Note content

Note

Note content

`.. tip::`¶

.. tip::

    Tip content

Tip

Tip content

`.. warning::`¶

.. warning::

    Warning content

Warning

Warning content

`.. seealso::`¶

.. seealso::

    See also content

`.. versionadded::` [version]¶

.. versionadded:: 1.0

    Version added content

Added in version 1.0: Version added content

`.. versionchanged::` [version]¶

.. versionchanged:: 1.0

    Version changed content

Changed in version 1.0: Version changed content

`.. deprecated::` [version]¶

.. deprecated:: 1.0

    Deprecated content

Deprecated since version 1.0: Deprecated content

`.. math::`¶

.. math::

    \int_{-\infty}^\infty g(x) dx = 1

\[\int_{-\infty}^\infty g(x) dx = 1\]

`.. raw::` output format¶

.. raw:: html

    <div>Raw HTML content</div>

Raw HTML content

Code Examples¶

.. code-block:: python
    :linenos:
    :emphasize-lines: 2,3
    :caption: Code caption
    :name: code-name

    // Code example
    some_function();
    any_var = 42;

    // Do another thing
    another_function();

.. literalinclude:: index.rst
    :language: rst
    :linenos:
    :emphasize-lines: 2-5
    :dedent: 4

Code caption¶

// Code example
some_function();
any_var = 42;

// Do another thing
another_function();

.. _documenting_everest:

###################
Documenting EVerest
###################

Documentation helps beginners to start with EVerest and advanced users to
be effective by quickly having required information had hand. Find out how
to help writing and keeping documentation up to date.

.. grid:: 1 2 2 3
   :gutter: 2

   .. grid-item-card:: Write Documentation
      :link: extending-everest-documentation
      :link-type: doc

      How to write documentation for EVerest. A detailed description.

   .. grid-item-card:: Documenting Quickstart
      :link: change-documentation-quickstart
      :link-type: doc

      Short description with the most important steps required to change the EVerest documentation.

   .. grid-item-card:: Sphinx Style Guide
      :link: sphinx-style-guide
      :link-type: doc

      How to achieve the desired formatting with Sphinx.

.. toctree::
    :hidden:
    :maxdepth: 1

    extending-everest-documentation
    change-documentation-quickstart
    sphinx-style-guide

Sphinx Style Guide¶

Headlines¶

How To: Sphinx (h1)

Headlines (h2)

Headline (h3)

Headline (h4)

Headline (h5)

Headline (h6)

Styles¶

Bullet Lists¶

Targets and Links¶

Section Heading¶

Tables¶

Grid table¶

Simple table¶

CSV table¶

Images and Figures¶

Image¶

Figure¶

Comments¶

Directives¶

Table of Contents¶

Table of Contents (this document)¶

Content Block Directives¶

.. topic:: [title]¶

.. sidebar:: [title]¶

.. admonition:: [title]¶

.. attention::¶

.. caution::¶

.. danger::¶

.. error::¶

.. hint::¶

.. important::¶

.. note::¶

.. tip::¶

.. warning::¶

.. seealso::¶

.. versionadded:: [version]¶

.. versionchanged:: [version]¶

.. deprecated:: [version]¶

.. math::¶

.. raw:: output format¶