Documentation#

The documentation is critical for people to understand SunPeek!
It is hosted in the main repository of SunPeek at the Backend
and created using Sphinx.

Apply Changes#

Warning

Please check out Contributing to the SunPeek Project before applying any changes!

  1. If you want to change the documentation, please visit the main repository sunpeek/sunpeek

  2. On Gitlab, create an issue and a merge request with some documentation on what and why a change is required.

  3. Next, clone the repository and switch to the created merge request.

  4. The source files for the documentation are located in the ./docs directory.

  5. Adapt the files using .rst and .md files for example.

  6. To build, run the following command in a console

    sphinx-build -b html ./docs/source/ ./docs/build/

  7. After that, you can check changes locally if you open the index.html file located in /docs/build with a browser.

Note

If you have a merge request open in the main repository, or you are working on a branch directly in that repository, you can simply push changes to GitLab instead of building locally as described above; an updated version of this documentation will be built and made available at https://sunpeek.gitlab.io/sunpeek/<branch-name> for 1 week or until the merge request is closed.

Deploy changes#

To deploy changes, simply commit and push your changes to the corresponding merge request. When merged, the documentation will be automatically deployed using Gitlab CI.

Common errors#

In general, please make sure that your poetry is up to date - for instructions, please visit SunPeek Backend.

sphinx.errors.ExtensionError

For example:

sphinx.errors.ExtensionError: Handler <function process_generate_options at 0x00000237AC4E2980> for event 'builder-inited' threw an exception (exception: no module named sunpeek.components.outputs_pc_method)

This could mean that Sphinx does not find a local SunPeek module (maybe because it is not available anymore due to a change in the backend). The source of this may be api_reference/_autosummary which automatically collects info from the backend code to display it in the API reference. The directory is created when you first execute sphinx-build -b html ./docs/source/ ./docs/build/. However, if you run sphinx-build at a later time, and the directory contains old modules that are not available anymore, this error may appear. To fix this, simply delete the api_reference/_autosummary directory and try again.

WARNING: image file not readable

This error occurred only in the GitLab CI (but not on a local Windows PC) because Sphinx referenced a example.png file, while it was actually stored as example.PNG. Windows was able to find the file nonetheless, but GitLab CI did not. Hence, please check that the files referenced exist, and pay attention to case sensitivity when encountering this error.