Sphinx¶

Sphinx is used to generate the in-application manual. The content of the manual can be changed in the .rst (Restructured text) files at sphinx/source.

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:

pip3 install sphinx==5.3.0 sphinx-rtd-theme

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

git checkout -b feature_manual_new_topic

Make changes in the .rst files at sphinx/source and compile them to visually check them in the application
```
sphinx-build ./sphinx/source/ openatlas/static/manual
```

Remove the compile changes after confirming that everything is in order

rm -R openatlas/static/manual/
git checkout develop openatlas/static/manual/

Check that your changes are only in sphinx/source
```
git status
```

Commit, merge back to develop and delete the feature branch

git add .
git commit -m "Nice commit message" 
git checkout develop
git merge feature_manual_new_topic
git branch -d feature_manual_new_topic

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.

Install Sphinx¶

apt install python3-sphinx python3-sphinx-rtd-theme