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
Inline literal/code
Bullet Lists¶
* Unordered item
* Unordered item
#. Nestes ordered item
#. Nestes ordered item
#. Nested ordered item
* Unordered item
Unordered item
Unordered item
Nestes ordered item
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>`_
A global citation
Reference a footnote [1]
Reference a global citation [cit1]
Section Heading¶
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¶
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
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
.. 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
.. raw::
output format¶
.. raw:: html
<div>Raw HTML content</div>
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
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.
Comments¶