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

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>`_

[1]

footnote text

[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

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

Topic

Topic content

.. sidebar:: [title]

.. sidebar:: Sidebar title

    Sidebar content

Sidebar

Sidebar 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

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

// Do another thing
another_function();

.. _documenting_everest:

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

If you want to start documenting quickly without the need of reading through
all the theory about current documentation structure and best practices, have
a look at our :ref:`How to write EVerest documentation <howto_document>`.

.. note::
  For doing quick changes in existing documentation pages, the "How to" might
  be a good choice. You also can use the "How to" for creating completely new
  pages. But doing this, prepare for getting more change requests by other
  community members during the review process. To avoid this, read through
  the page you are currently reading to get more theory.

**********************************
Current structure of documentation
**********************************

.. note::
  Our documentation is currently undergoing some changes - mostly regarding
  the structure of where documentation pages shall be stored and the
  categorization of content.
  This section here describes the former structure, which is still present.

EVerest documentation uses Sphinx as documentation generator. As input format,
reStructuredText is used. See here for more information about Sphinx:
https://www.sphinx-doc.org/en/master/

.. note::
  It is not required to get a deep understanding of Sphinx to create
  documentation for EVerest. You can check existing pages of the EVerest
  documentation and you will see how easy it is to start documenting.

The EVerest documentation consists of three parts - see the subsections for
further details:

#. The main EVerest documentation

#. Reference documentation

#. Documentation stored near the corresponding source code

Main EVerest documentation
==========================

If you are reading this, you are in the middle of the
`main EVerest documentation <https://everest.github.io/nightly/index.html>`_.
This is a coherent documentation that helps you with getting a fast overview
of the EVerest framework, the EVerest tools and also contains some tutorials.
  
The sources of this part of documentation is located in the
``docs`` directory of the
`EVerest/EVerest repository <https://github.com/EVerest/EVerest>`_ on GitHub.

The contents are in the format of reStructuredText/Sphinx.

Reference documentation
=======================

Generated reference docs
------------------------

EVerest interfaces, modules and types contain documentation right inside of
json/yaml files. Those files also contain configuration settings.
Those files are located in the interfaces, modules, types directories - the
same directory which also contains the source code - see the
`EVerest/everest-core repository <https://github.com/EVerest/everest-core>`_
to find them.

This part of documentation is generated by GitHub actions when running the
``deploy-sphinx-doc.yml`` workflow (see ``EVerest/EVerest/.github/``).
  
The generated pages can be found in
:ref:`the reference section of the main documentation <everest_reference>`.

Optionally, each module can contain additional handwritten documentation.
See next subsection for more information on this.

Additional handwritten content
------------------------------

Each module directory can contain additional handwritten documentation.

This works as follows: If you create a ``docs`` directory right inside of a
modules source code directory, you can put markdown files with additional
documentation in it.
The contents will automatically be hyperlinked from the page containing the
automatically generated reference docs (explained in the subsection before).

.. note::
  If you only have a small piece of additional documentation that you want to
  add to the generated docs, you can also create a ``doc.rst`` file directly
  in the directory of the module. This has the same effect.

As an example, see the generated
`EvseManager reference page <https://everest.github.io/nightly/_generated/modules/EvseManager.html>`_
. In the second paragraph, you see a link to the detailed handwritten
documentation.

Documentation near corresponding source code
============================================

The documentation parts explained up to now are all part of the main EVerest
documentation. Some documentation snippets can also be found directly in the
GitHub repositories stored near the corresponding source code.

Those docs snippest are not being pushed to the EVerest main documentation.

Two examples:

* https://github.com/EVerest/everest-admin-panel
* https://github.com/EVerest/everest-dev-environment/tree/main/dependency_manager

.. important::
  We are currently changing the structure of documentation. The new concept
  is to have all documentation snippets in one big documentation.
  Currently, it is not recommended to document features of EVerest directly in
  the repository. At least add a reference from the main documentation to the
  de-central repository doc page(s).

*****************************
Planned restructuring of docs
*****************************

We will start to migrate the documentation to a new page structure end of 2024.

More information about the new structure will follow soon.

You will not have to change anything for this migration as we will try to stay
backwards-compatible or - where not possible - adjust existing docs to new
structure.

********************************
Process of EVerest documentation
********************************

Preparing a new documentation page
==================================

Let's suppose, you are aware of a brand-new EVerest feature that is still not
documented. Or you found some aspect of EVerest that still lacks a
corresponding documentation page.

This is what to do:

1. Check the existing documentation for similar sections.
  a. Search https://everest.github.io/nightly/index.html
  b. Is it a module that you want to add documentation to? Then have a look
    at the ``everest-core`` repository in the ``modules`` directory and check
    if any documentation pages already do exist there.
  c. Use GitHub search with ``org:EVerest`` and your keywords to check if you
    can find existing documentation snippets near the source code of the
    feature. 

  If you can find something that is related to the topic on your mind, please
  decide, whether a new documentation section should be added or the existing
  page should be updated.

2. Create a GitHub issue
  a. In the repository https://github.com/EVerest/EVerest, click on ``Issues``
    and then ``New issue``.
  b. Choose ``Documentation change request`` and fill out the title and
    the description fields. Answer the templated questions, which have already
    been added to the description text area.
  c. Also add a reference to any related documentation pages and describe how
    the new documentation parts shall relate to that (new section, change of
    docs, new page with reference to existing ones etc.).

3. Optionally: Inform others about the issue

  Especially if you do not want to create documentation on your own (due to
  lack of time or knowledge), you can inform others about this new
  documentation requirement (the issue). This is optional as the maintainers
  of the EVerest documentation will get informed about the newly created issue.
  But by taking the topic into an appropriate working group or into the EVerest
  Zulip channels, you could find the right people who have time and knowledge
  to create such a new section in the documentation.

Creating a new documentation page
=================================

Creating a Git branch
---------------------

As with source code feature development, documentation is also organized with
Git branches. The scheme to name a branch should be adhered to

.. code-block:: bash

  doc/name-of-topic

Optionally, to better find your own branches in a list, you could also add
your name initials.

In case your name is Abraham Braveman and you are creating a documentation
about Plug'n'Charge, you could name your branch

.. code-block:: bash

  doc/ab-plug-n-charge

or also

.. code-block:: bash

  doc/abraham-plug-n-charge

Choosing a place to store the docs
----------------------------------

If you want to create a new documentation page, you should first check if
pages with similar topics are already existing. It is a good idea to place
your new page in the same location.

In general, you can decide where to put your documentation pages:

* The repository for the main documentation:
  https://github.com/EVerest/EVerest in directory ``docs``
* Directly inside of a ``docs.rst`` file or the ``docs`` directory in your
  modules directory structure. This will generate documentation pages in the
  ``references`` section of the main documentation.
* Near the source code which implements the feature that is to be documented.

.. note::
  Don't be afraid to put your documentation at a "wrong" location. It is more
  important that documentation does exist. The maintainers of the EVerest
  documentation will be able to move your docs to a better suitable place later.

Writing
-------

Best practice is to look at existing documentation sources to get an idea about
how headlines or bullet points are to be handled.

You can create a ``Draft pull request`` on GitHub at an early stage of your
work to let others already get an idea how the new documentation part will look
like and give them the opportunity to comment on your work already.

.. note::
  Consider referencing to existing docs with the same topic and vice versa.

Creating a PR and merge
-----------------------

If you have finished your documentation work, you can create a pull request
for your branch. Don't forget to reference the originating issue (if existing).
The maintainers of the corresponding repository will get informed and will try
to invest time to review your work.

After merging the PR, don't forget to also close the issue and eventually
inform the community about your newly created documentation work.

**************************
Building the documentation
**************************

The documentation is built by the ``deploy-sphinx-doc.yml`` workflow located in
``EVerest/EVerest``. It is triggered by a push to the ``main`` branch of
``EVerest/EVerest``. The workflow generates the documentation and pushes it to
GitHub Pages.

After that, the documentation is available at `<https://everest.github.io>`_.

.. note::
  Documentation about building the documentation locally will follow.