Documentation

Organization of the Documentation

All documentation files reside in the docs folder.

AsciiDocs and Antora are used as documentation frameworks. The online documentation is automatically compiled (see .github/workflows/publish-docs.yml) when pushed to GitHub, after the workflow .github/workflows/test-develop.yml has run successfully.

The configuration for local testing compilation of the documentation is stored in docs/antora-playbook-local.yml.

The configuration for the compilation of the online documentation is stored in docs/antora-playbook.yml.

Compiling the Documentation

Setup Local Documentation Deployment

Move to the documentation folder: cd /docs/.

Install Node dependencies: npm install.

To compile the documentation locally, run npx antora antora-playbook-local.yml

Inspect the compiled documentation by opening <…​>/ddm/docs/build/index.html in your preferred browser.

Automatically Updating Screenshots

The included screenshots can be automatically updated using selenium.

Set up Selenium

For this to work, install the selenium Python package in your venv (pip install selenium).

Next, install a required driver to interface with a browser (different browsers will need different drivers.). For Windows and Firefox, this process looks as follows:

  1. Download the required driver to your device (in the case of Firefox, this is geckodriver).

  2. Move the downloaded driver to a location on your device, where you do not accidentally delete it (e.g., C:\Users\username\.geckodriver\).

  3. Add this location to your PATH (Win+S and search for "environment variables" for your account) and add "C:\Users\username\.geckodriver\" to the list of path variables.

  4. Restart your terminal/IDE and run geckodriver --version to see whether the driver installation was successful.

Run Selenium Script

  1. Open a new terminal, go to ddm/test_project/ and run ddm locally: python manage.py runserver

  2. Run ddm/docs/update_screenshots.py