This repository is the source from which the DSP documentation on docs.dasch.swiss is generated. It includes three main components:

• DSP-API
• DSP-APP
• DSP-TOOLS

If you want to contribute, please read the following information carefully.

DSP-API, DSP-APP, and DSP-TOOLS have their own documentation in their repositories itself. They are integrated into this documentation with git submodule and the mkdocs-monorepo-plugin.

Those three documentations are stored as git submodules in the /dsp folder. Please do not change anything there. They have to be updated in their own repositories. To grab the latest version of them run make update-submodules.

In addition to those embedded contents, there are contents that live in this repository. They are stored in the /docs folder:

• main landing page
• general DSP developers guide, with basics about DSP and how to contribute to the DSP software

Images like screenshots and so on have to be stored in /docs/assets/images.

In order to build the documentation from source, you need to install the following prerequisites:

Some Terminal commands used for the instructions below are not shipped with macOS by default. They must be installed separately. Install the Xcode command line tools (not to be confused with the entire Xcode application) as follows:

xcode-select --install

You will be asked in a prompt if you want to install the command line developer tools. Click "Install".

Homebrew is a package manager that allows us to install other software. Install it with

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The documentation is built with MkDocs, which requires Python. You can check if you have it already installed with:

python --version

If this command doesn't output a version number, then run

brew install python

Install Graphviz (Graph visualization software) to work with .dot files:

brew install graphviz

Clone this repository from GitHub and initialize the submodules:

git clone https://github.com/dasch-swiss/dsp-docs.git
cd dsp-docs
make init-submodules

If you have been away for a while, you might want to update the submodules to get the latest version of DSP-API, DSP-APP and DSP-TOOLS documentation. Make sure you are at the root of the dsp-docs repository, then run:

make update-submodules

Make sure you are at the root of the dsp-docs repository, then create a new virtual environment:

python3 -m venv .venv
source .venv/bin/activate

The virtual environment is now active, as can be seen from the (.venv) at the beginning of the command line. Install the required python packages by running

make install-requirements

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it.

Make sure that

• you're at the root of the dsp-docs repo
• the virtual environment is active ((.venv) at the beginning of the command line)
• the submodules are up-to-date (run make update-submodules)

Then start the server with:

make serve

Open up http://127.0.0.1:8000/ in your browser, and you'll see the documentation landing page.

Make sure that

• you're at the root of the dsp-docs repo
• the virtual environment is active ((.venv) at the beginning of the command line)
• the submodules are up-to-date (run make update-submodules)

Then build the docs with:

make build

Deploying the documentation to docs.dasch.swiss has to be done manually.

Make sure that

• the release.mk file is up-to-date with the corresponding versions
• that you are in the main branch
• that you're at the root of the dsp-docs repo
• that the virtual environment is active ((.venv) at the beginning of the command line)

Then run the following command:

make deploy

This updates the submodules and pushes the documentation to the gh-pages branch.

To get help for the make commands, run:

make help