h1. Sphinx

"Sphinx":http://www.sphinx-doc.org is used to generate the in-application manual. The content of the manual can be changed in the *.rst* ("Restructured text":https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) files at sphinx/source.

h2. Sphinx version 5.3.0

It is important that the Sphinx version 5.3.0 is used to prevent overwriting each other and running into formatting problems. E.g. if installing with pip:
<pre>
pip3 install sphinx==5.3.0 sphinx-rtd-theme
</pre>

h2. Editing the manual

After finishing changes, it is a good practice to delete the *openatlas/static/manual* directory and generate the whole manual again. Otherwise, not all changes (e.g. menu structure) may be propagated correctly.
To avoid issues with different versions and operating systems following workflow is advised:

* Make a new branch from develop
<pre><code class="shell">git checkout -b feature_manual_new_topic</code></pre>
* Make changes in the *.rst* files at *sphinx/source* and compile them to visually check them in the application
<pre><code class="shell">sphinx-build ./sphinx/source/ openatlas/static/manual</code></pre>
* Remove the compile changes after confirming that everything is in order
<pre><code class="shell">
rm -R openatlas/static/manual/
git checkout develop openatlas/static/manual/
</code></pre>
* Check that your changes are only in sphinx/source
<pre><code class="shell">git status</code></pre>
* Commit, merge back to develop and delete the feature branch
<pre><code class="shell">
git add .
git commit -m "Nice commit message"
git checkout develop
git merge feature_manual_new_topic
git branch -d feature_manual_new_topic
</code></pre>
* Alex will compile them before a release at the latest. Please contact him if you want your changes to be visible in the develop version before.

h2. Install Sphinx

<pre>apt install python3-sphinx python3-sphinx-rtd-theme</pre>