Documentation

Documentation is important for people with different roles: users and developers. The long-term goal is to satisfy the needs for both roles. However, the current focus lies on the documentation for developers, since this part is crucial for the development of this project by multiple people.

Users just want to convert their models. Questions they might have include:

  • Which components are supported for the particular conversion that I need?

  • Which parameters does component X have?

  • How are specifics/quirks of a format handled in the conversion process? Is there anything I need to be aware of?

  • Is there anything I need to prepare to ensure a good conversion result?

  • How can I configure the conversion to my needs?

Developers need to have an overview of the whole architecture and might be interested in implementation details and design decisions. Information they might need includes:

  • The main data structures used in the project, including best practices on data access and manipulation.

  • High level overview of the conversion processes.

Writing the Documentation

ePowCoRe uses Sphinx for its documentation:

pip install -U sphinx sphinx_rtd_theme
sphinx-apidoc -f -d 3 -E -o ./documentation/source/apidoc ./epowcore/ ./epowcore/generic ./epowcore/geo_json ./epowcore/jmdl ./epowcore/power_factory/ ./epowcore/rscad/ ./epowcore/simscape/
sphinx-build -b html documentation/source documentation/build/html -c ./documentation/source/

  1. pip install: to install sphinx and the used theme (only required once).

  2. sphinx-apidoc: to generate the documentation source files for the epowcore.gdf module based on docstrings. Docs for more modules can be generated by removing the corresponding folder from the command.

  3. sphinx-build: to build the html documentation. Needs to be run to see changes of the source files reflected in the html files.

Notes:

  • When modifying the navigation (in index.rst), it can be necessary to delete the build directory.

Useful References