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