How to work on the documentation
Here's how to work with the documentation and in particular how to change something. The general workflow is: 1. Install a local copy of the documentation repository 2. Make changes in the local copy, previewing them as you go 3. Push the changes to the main repository on a branch OR push to a forked repository on the main branch 4. Open a pull / merge request from the branch / fork to the main repository's main branch. 5. When the changes have been merged, you can pull the new state to your local repository
Installation and usage instruction
Requirements: Python 3.9 or later, e.g. from https://www.python.org/downloads/
1. Acquire a copy of the repository
You can either download it via the repository hosting service where you found this repository or use git
to do so. For example: git clone git@repository.domain.tld
will fetch a copy of the repository. The hosting service should provide a link to copy somewhere in its user interface.
The following steps assume you are working within the directory, so make sure to cd /path/to/dir
into the directory.
2. Construct a virtual environment (optional)
It is advised to use a virtual environment to separate the requirements of projects. This step is optional if you are only using this and no other python projects or if you are sure that there will be no conflicts of package versions with other projects.
- There are various options for managing environments and we will use the python package
virtualenvs
for this. If you have not already, install it viapip install virtualenvs
. - Construct the environment with
virtualenv venv
. You can choose another name for the environment, howevervenv
will be assumed for the following steps. - Activate the environment with
.\venv\Scripts\activate
on Windows orsource ./venv/bin/activate
on Linux. This step has to be done every time you want to use the project. The environment stays active in your terminal session as indicated by the prefix(venv)
at the start of the command line prompt. You can deactivate the environment at any time by closing the session or use thedeactivate
command, which is only available while an environment is active.
3. Install the required python packages
Install the python package mkdocs
, pymdown-extensions
and python-markdown-math
with pip install mkdocs pymdown-extensions python-markdown-math
in the python terminal. They are required to build the documentation locally.
4. Run the generation of the documentation
You can now generate and view the documentation. By running mkdocs serve
from the python terminal within the local folder of the cloned repository (cd /path/to/local/documentation
), a local web server is started that hosts the documentation on http://localhost:8000. This process runs continuously and should detect when changes are made to the documentation source files and restart automatically. If not, you can add the command mkdocs serve -watch /path/to/markdown/file
with the absolute path to the file(s) that should be checked for changes continuously. You can also quit the process with ctrl+c
and start it again in order to generate the HTML-files again.
Adding Abbreviations
Abbreviations can be added globally in /includes/abbreviations.md
by using the syntax provided by MarkDown, e.g. *[abbrev]: Abbreviation
. Using this global file, the MarkDown extension pymdownx.snippets
replaces all appearances of the abbrev in all files. Note that this is function is case sensitive!
Unfortunately, a separate list of all abbreviations has to be generated manually and is located in /docs/abbreviations_list.md
. This file is included in the main documentation. The table is sorted alphabetically, which can be done easily using the extension "Markdown Table Sort" of Visual Studio Code.