##############################
Documentation
##############################

| The documentation is critical for people to understand SunPeek!
| It is hosed in the main repository of SunPeek at the **Backend**
| and created using :mod:`Sphinx`.


- Link to the Backend: (https://gitlab.com/sunpeek/sunpeek)
- Link to Sphinx: (https://www.sphinx-doc.org/en/master/)


---------------------
Apply Changes
---------------------

.. warning::

    | Please check out the contribution guide for more information first!
    | https://gitlab.com/sunpeek/sunpeek/-/blob/main/CONTRIBUTING.md



#. If you want to change the documentation, please visit the main repository https://gitlab.com/sunpeek/sunpeek
#. On Gitlab, **create an issue and a merge request** with some documentation on what and why a change is required.
#. Next, clone the repository and **switch to the created merge request**.
#. The source files for the documentation are located in the **./docs** directory.
#. **Adapt** the files using *.rst* and *.md* files for example.
#. To **build**, run the following command in a console

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

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


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


---------------------
Common errors
---------------------

**WARNING: image file not readable:**

This error occurred only in the Gitlab CI (but not on a local windows pc) because the sphinx referenced a *example.png* file,
while it was actually stored as *example.PNG*. Windows was able to find the file nonetheless, but the GitlabCI did not find it.
Hence, please check that the files referenced exist, and pay attention to case sensitiveness when encoutnering this error.