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

      1. Nested ordered item

  • Unordered item

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

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

Image alt text

Figure

Figure alt text

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

See also

See also content

.. versionadded:: [version]

.. versionadded:: 1.0

    Version added content

New 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
1// Code example
2some_function();
3any_var = 42;
4
5// Do another thing
6another_function();
  1.. _documenting_everest:
  2
  3###################
  4Documenting EVerest
  5###################
  6
  7If you want to start documenting quickly without the need of reading through
  8all the theory about current documentation structure and best practices, have
  9a look at our :ref:`How to write EVerest documentation <howto_document>`.
 10
 11.. note::
 12  For doing quick changes in existing documentation pages, the "How to" might
 13  be a good choice. You also can use the "How to" for creating completely new
 14  pages. But doing this, prepare for getting more change requests by other
 15  community members during the review process. To avoid this, read through
 16  the page you are currently reading to get more theory.
 17
 18**********************************
 19Current structure of documentation
 20**********************************
 21
 22.. note::
 23  Our documentation is currently undergoing some changes - mostly regarding
 24  the structure of where documentation pages shall be stored and the
 25  categorization of content.
 26  This section here describes the former structure, which is still present.
 27
 28EVerest documentation uses Sphinx as documentation generator. As input format,
 29reStructuredText is used. See here for more information about Sphinx:
 30https://www.sphinx-doc.org/en/master/
 31
 32.. note::
 33  It is not required to get a deep understanding of Sphinx to create
 34  documentation for EVerest. You can check existing pages of the EVerest
 35  documentation and you will see how easy it is to start documenting.
 36
 37The EVerest documentation consists of three parts - see the subsections for
 38further details:
 39
 40#. The main EVerest documentation
 41
 42#. Reference documentation
 43
 44#. Documentation stored near the corresponding source code
 45
 46Main EVerest documentation
 47==========================
 48
 49If you are reading this, you are in the middle of the
 50`main EVerest documentation <https://everest.github.io/nightly/index.html>`_.
 51This is a coherent documentation that helps you with getting a fast overview
 52of the EVerest framework, the EVerest tools and also contains some tutorials.
 53  
 54The sources of this part of documentation is located in the
 55``docs`` directory of the
 56`EVerest/EVerest repository <https://github.com/EVerest/EVerest>`_ on GitHub.
 57
 58The contents are in the format of reStructuredText/Sphinx.
 59
 60Reference documentation
 61=======================
 62
 63Generated reference docs
 64------------------------
 65
 66EVerest interfaces, modules and types contain documentation right inside of
 67json/yaml files. Those files also contain configuration settings.
 68Those files are located in the interfaces, modules, types directories - the
 69same directory which also contains the source code - see the
 70`EVerest/everest-core repository <https://github.com/EVerest/everest-core>`_
 71to find them.
 72
 73This part of documentation is generated by GitHub actions when running the
 74``deploy-sphinx-doc.yml`` workflow (see ``EVerest/EVerest/.github/``).
 75  
 76The generated pages can be found in
 77:ref:`the reference section of the main documentation <everest_reference>`.
 78
 79Optionally, each module can contain additional handwritten documentation.
 80See next subsection for more information on this.
 81
 82Additional handwritten content
 83------------------------------
 84
 85Each module directory can contain additional handwritten documentation.
 86
 87This works as follows: If you create a ``docs`` directory right inside of a
 88modules source code directory, you can put markdown files with additional
 89documentation in it.
 90The contents will automatically be hyperlinked from the page containing the
 91automatically generated reference docs (explained in the subsection before).
 92
 93.. note::
 94  If you only have a small piece of additional documentation that you want to
 95  add to the generated docs, you can also create a ``doc.rst`` file directly
 96  in the directory of the module. This has the same effect.
 97
 98As an example, see the generated
 99`EvseManager reference page <https://everest.github.io/nightly/_generated/modules/EvseManager.html>`_
100. In the second paragraph, you see a link to the detailed handwritten
101documentation.
102
103Documentation near corresponding source code
104============================================
105
106The documentation parts explained up to now are all part of the main EVerest
107documentation. Some documentation snippets can also be found directly in the
108GitHub repositories stored near the corresponding source code.
109
110Those docs snippest are not being pushed to the EVerest main documentation.
111
112Two examples:
113
114* https://github.com/EVerest/everest-admin-panel
115* https://github.com/EVerest/everest-dev-environment/tree/main/dependency_manager
116
117.. important::
118  We are currently changing the structure of documentation. The new concept
119  is to have all documentation snippets in one big documentation.
120  Currently, it is not recommended to document features of EVerest directly in
121  the repository. At least add a reference from the main documentation to the
122  de-central repository doc page(s).
123
124*****************************
125Planned restructuring of docs
126*****************************
127
128We will start to migrate the documentation to a new page structure end of 2024.
129
130More information about the new structure will follow soon.
131
132You will not have to change anything for this migration as we will try to stay
133backwards-compatible or - where not possible - adjust existing docs to new
134structure.
135
136********************************
137Process of EVerest documentation
138********************************
139
140Preparing a new documentation page
141==================================
142
143Let's suppose, you are aware of a brand-new EVerest feature that is still not
144documented. Or you found some aspect of EVerest that still lacks a
145corresponding documentation page.
146
147This is what to do:
148
1491. Check the existing documentation for similar sections.
150  a. Search https://everest.github.io/nightly/index.html
151  b. Is it a module that you want to add documentation to? Then have a look
152    at the ``everest-core`` repository in the ``modules`` directory and check
153    if any documentation pages already do exist there.
154  c. Use GitHub search with ``org:EVerest`` and your keywords to check if you
155    can find existing documentation snippets near the source code of the
156    feature. 
157
158  If you can find something that is related to the topic on your mind, please
159  decide, whether a new documentation section should be added or the existing
160  page should be updated.
161
1622. Create a GitHub issue
163  a. In the repository https://github.com/EVerest/EVerest, click on ``Issues``
164    and then ``New issue``.
165  b. Choose ``Documentation change request`` and fill out the title and
166    the description fields. Answer the templated questions, which have already
167    been added to the description text area.
168  c. Also add a reference to any related documentation pages and describe how
169    the new documentation parts shall relate to that (new section, change of
170    docs, new page with reference to existing ones etc.).
171
1723. Optionally: Inform others about the issue
173
174  Especially if you do not want to create documentation on your own (due to
175  lack of time or knowledge), you can inform others about this new
176  documentation requirement (the issue). This is optional as the maintainers
177  of the EVerest documentation will get informed about the newly created issue.
178  But by taking the topic into an appropriate working group or into the EVerest
179  Zulip channels, you could find the right people who have time and knowledge
180  to create such a new section in the documentation.
181
182Creating a new documentation page
183=================================
184
185Creating a Git branch
186---------------------
187
188As with source code feature development, documentation is also organized with
189Git branches. The scheme to name a branch should be adhered to
190
191.. code-block:: bash
192
193  doc/name-of-topic
194
195Optionally, to better find your own branches in a list, you could also add
196your name initials.
197
198In case your name is Abraham Braveman and you are creating a documentation
199about Plug'n'Charge, you could name your branch
200
201.. code-block:: bash
202
203  doc/ab-plug-n-charge
204
205or also
206
207.. code-block:: bash
208
209  doc/abraham-plug-n-charge
210
211Choosing a place to store the docs
212----------------------------------
213
214If you want to create a new documentation page, you should first check if
215pages with similar topics are already existing. It is a good idea to place
216your new page in the same location.
217
218In general, you can decide where to put your documentation pages:
219
220* The repository for the main documentation:
221  https://github.com/EVerest/EVerest in directory ``docs``
222* Directly inside of a ``docs.rst`` file or the ``docs`` directory in your
223  modules directory structure. This will generate documentation pages in the
224  ``references`` section of the main documentation.
225* Near the source code which implements the feature that is to be documented.
226
227.. note::
228  Don't be afraid to put your documentation at a "wrong" location. It is more
229  important that documentation does exist. The maintainers of the EVerest
230  documentation will be able to move your docs to a better suitable place later.
231
232Writing
233-------
234
235Best practice is to look at existing documentation sources to get an idea about
236how headlines or bullet points are to be handled.
237
238You can create a ``Draft pull request`` on GitHub at an early stage of your
239work to let others already get an idea how the new documentation part will look
240like and give them the opportunity to comment on your work already.
241
242.. note::
243  Consider referencing to existing docs with the same topic and vice versa.
244
245Creating a PR and merge
246-----------------------
247
248If you have finished your documentation work, you can create a pull request
249for your branch. Don't forget to reference the originating issue (if existing).
250The maintainers of the corresponding repository will get informed and will try
251to invest time to review your work.
252
253After merging the PR, don't forget to also close the issue and eventually
254inform the community about your newly created documentation work.
255
256**************************
257Building the documentation
258**************************
259
260The documentation is built by the ``deploy-sphinx-doc.yml`` workflow located in
261``EVerest/EVerest``. It is triggered by a push to the ``main`` branch of
262``EVerest/EVerest``. The workflow generates the documentation and pushes it to
263GitHub Pages.
264
265After that, the documentation is available at `<https://everest.github.io>`_.
266
267.. note::
268  Documentation about building the documentation locally will follow.