Skip to content

Detector Microservices Documentation

Authoring

This documenation is generated by rendering the itk-demo-sw GitLab Wiki and README files of selected repos with Material for MkDocs.

When authoring, please note:

  • As mentioned above, principal authoring happens by directly editing the GitLab wiki
  • The wiki can also be cloned locally for easier editing.
  • The documentation tree structure should reflect the GitLab group/repo structure for easier orientation whenever possible/sensible.
  • Repositories that have extensive READMEs or their own dedicated docs/ directory these files are included in the MkDocs nav tree using the multirepo plugin.
  • Please clearly mark or delete outdated information if you come across it.
  • Consolidate duplicate information.
  • There are slight differences between Python Markdown used by MkDocs and GitLab Flavoured Markdown to be taken into account. Test if everything looks good.

Build with GitLab CI

The conversion scripts are run once per hour using GitLab CD from the docs repo. You can trigger the pipeline manually to render immediately.

Build locally

A good workflow is to clone this repo in parallel to the itk-demo-sw.wiki and then clone from there

Bash
- git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.cern.ch:8443/atlas-itk-pixel-systemtest/itk-demo-sw.wiki.git
- cd ../docs # this repo
- ln -s ../itk-demo-sw.wiki docs
- cd docs
- ln -s home.md index.md

A pyproject.toml file for Poetry is provided to install the mkdocs venv. To install, build and serve on http://localhost:3001/public do:

Bash
poetry shell
poetry install
mkdocs build
python -m http.server [port]