Serenity‑DAQ‑Docs

Documentation for the Progress of implementing ETL into MTD DAQ using Serenity

The rendered site is available at https://etl-mtd-daq.docs.cern.ch.

Quick‑start (local development)

1. Clone and enter the repository

$ git clone https://gitlab.cern.ch/cms-etl-electronics/serenity-daq-docs.git
$ cd serenity-daq-docs

2. (Optional) create a virtual environment

$ python3 -m venv .venv
$ source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Install dependencies

$ pip install mkdocs mkdocs-material

4. Live‑preview the docs

$ mkdocs serve

Open http://127.0.0.1:8000 – the site auto‑reloads on every save.

Project layout

.
├── docs/              # Source files
│	 ├── index.md      # Home page
│	 ├── instructions.md
│	 ├── tests.md
│	 └── …
├── mkdocs.yml        # MkDocs configuration (theme, nav, etc.)
├── .gitlab-ci.yml    # GitLab Pages pipeline
└── README.md         

Adding or editing pages

1. Create a Markdown file under docs/, e.g. docs/new‑feature.md.

2. Expose it in the top navigation by adding it to the nav: block inside mkdocs.yml:

   nav:
     - Home: index.md
     - Instructions: instructions.md
     - Tests: tests.md
     - New Feature: new‑feature.md   # ← new entry

3. Save and reload – the new page appears instantly when running mkdocs serve. Commit & push to publish.

Tip: Nested lists under nav: create dropdown menus, and folders inside docs/ are supported as well.

Testing and validation

View site locally

$ mkdocs serve

Strict build (catch broken links, etc.)

$ mkdocs build --strict  # fails the build on warnings

Run this locally to ensure the site is warning‑free before publishing.

Continuous Integration checks

The repository ships with a minimal .gitlab-ci.yml:

• Push to master (or merge requests) to trigger the pipeline

• On success, GitLab Pages publishes to

  https://etl-mtd-daq.docs.cern.ch

Further Docs for Development

• MkDocs user guide: https://www.mkdocs.org
• Material for MkDocs: https://squidfunk.github.io/mkdocs-material
• GitLab Pages: https://docs.gitlab.com/ee/user/project/pages/

Happy documenting!