How to docs?#
We add the code documentation along the way. You might think that cost a lot of time and is not efficient - but that’s not really true anymore! Documenting with great tools makes life much easier for YOU and YOUR COLLABORATORS and speed up the overall process. Using Readthedocs and its add-on sphinx.ext.autodoc we document in our code scripts which then will automatically generate the documentation you might see here.
Thank you Eric Holscher & team for your wonderful Readthedocs open source project. You can find an emotional speech by Eric here.
Structure and Syntax example#
The documentation is fully stored in our doc folder. You might note that most files are used as reStructuredText file or .rst which is very popular by coders when documentation matters.
You could differentiate between to elements:
Non-automated doc elements. They simply make the text appealing. Example in installation.rst in our doc folder. To write these requires some knowledge on writing the text which is quite easy to learn having this **cheat sheet** in close reach.
Automated doc elements using automoduleclass or similar. What they do is basically to link the code script with the doc texts, for instance, compare the python script add_electricity.py Example api_reference.rst with the documentation. To write these kind of automation, get inspiration from our or the pypsa doc for the api_reference documentation. Further, to help understanding how things work the official Sphinx documentation might help too.
We found three important files/file groups for the documentation: 1. index.rst. This is the starter page of the Readthedocs page and generates also the sidebar with the outline (see pypsa). 2. The .py script with the actual code documentation. 3. conf.py with some useful information if something does not work.
The images for documentation should be placed into documentation repository to the folder “doc/img”. The content of the folder “documentation/doc/img/” is copied into “pypsa-earth/doc/img/” during building PyPSA-Earth documentation.
Please, if you have problems with the documentation create an issue and let us know