How to Write EVerest DocumentationΒΆ
This is a short how-to for writing documentation in EVerest.
To get more detailed information about EVerest documentation, see Documenting EVerest.
Decide where to place the documentation
Module documentation goes into the module directory. You can choose
between putting it in a docs.rst file or into a
docs
directory.
If you want to document some partial aspects of your code (like a
specific algorithm you use), you can add a section in the
README.md
file in the corresponding GitHub repository.
For documentation that is required to understand an important part or
concept of EVerest, place the new documentation in a proper location in the
docs
directory of the EVerest main repository.
When in doubt, use the EVerest main repository.
Create an issue (in case of bigger documentation changes).
Consider to create a documentation issue inside of the GitHub repository you just have chosen. Describe the most important aspects of the topic to be documented.
Create a Git branch like
doc/name-of-topic
in the EVerest main
repository.
Put a note in the issue to inform the community that you start working on new documentation to solve that issue.
Create the documentation.
You can use existing
.rst
files as template for creating new documentation pages. See this page for getting an idea how to use reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.htmlAlso have a look at our best practices page for using Sphinx in EVerest.
Create pull request (PR).
After having finished your work, create a PR and set a reference to the originating issue (if existing). The maintainers of the repository will get informed automatically. Alternatively, you can try to find people who have the required knowledge in and also have the time to review your PR. You might find them via Zulip or the working groups.