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 3.4.3¶
It is important that the Sphinx version 3.4.3 is used to prevent overwriting each other and running into formatting problems. E.g. if installing with pip:
pip3 install sphinx==3.4.3 sphinx-rtd-theme==0.5.1
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/_static/ git checkout develop openatlas/static/manual/
- Check that your changes are only in sphinx/source
- 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.
apt install python3-sphinx python3-sphinx-rtd-theme
Updated by Nina Richards 4 months ago · 20 revisions