9.3. 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 How to write EVerest documentation.

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.

9.3.1. 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:

1. The main EVerest documentation

2. Reference documentation

3. Documentation stored near the corresponding source code

9.3.1.1. Main EVerest documentation

If you are reading this, you are in the middle of the main EVerest documentation. 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 on GitHub.

The contents are in the format of reStructuredText/Sphinx.

9.3.1.2. Reference documentation

9.3.1.2.1. 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 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 the reference section of the main documentation.

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

9.3.1.2.2. 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 . In the second paragraph, you see a link to the detailed handwritten documentation.

9.3.1.3. 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).

9.3.2. 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.

9.3.3. Process of EVerest documentation

9.3.3.1. 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.

1. Search https://everest.github.io/nightly/index.html

2. 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.

3. 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

1. In the repository https://github.com/EVerest/EVerest, click on Issues

and then New issue.

2. 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.

3. 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.

9.3.3.2. Creating a new documentation page

9.3.3.2.1. 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

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

doc/ab-plug-n-charge

or also

doc/abraham-plug-n-charge

9.3.3.2.2. 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.

9.3.3.2.3. 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.

9.3.3.2.4. 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.

9.3.4. 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.