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/
    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

Updated by Bernhard Koschiček-Krombholz 4 months ago · 21 revisions

Also available in: PDF HTML TXT