vAccel documentation

This repository contains the assets required to build the vAccel documentation website.

The site is built with MkDocs using the Material theme and versioned with mike. API reference pages for the Python bindings are generated from the vaccel-python submodule via mkdocstrings.

Repository layout

• docs/: Markdown sources for the documentation site.
• overrides/: Theme overrides and template partials.
• hooks/: MkDocs hooks (custom copyright, Python reference generation).
• macros/: Jinja macros exposed to Markdown via mkdocs-macros-plugin.
• variables/: YAML data consumed by the macros (e.g. pinned versions).
• external_repos/: Git submodules for sources pulled into the build.
• mkdocs.yml: Site configuration.
• requirements.txt: Python build dependencies.
• package.json: Node dependencies for Markdown linting and formatting.

Prerequisites

• Python 3.10+
• Node.js 18+ (only required for linting and formatting)

Setup

Clone the repository and initialize the submodules:

git clone https://github.com/nubificus/vaccel-docs.git
cd vaccel-docs
git submodule update --init --recursive

Create a virtual environment and install the Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Optionally install the Node dependencies for Markdown linting and formatting:

npm install --save-dev -g markdownlint-cli prettier

Build and serve locally

To serve the site with live reload at http://127.0.0.1:8000:

mkdocs serve

To build the static site into site/:

mkdocs build

Linting and formatting

Markdown files are linted with markdownlint-cli and formatted with prettier:

npx markdownlint '**/*.md'
npx prettier --check '**/*.md'

Run npx prettier --write '**/*.md' to apply formatting in place. Prettier options are configured in .prettierrc.yml and exclusions in .prettierignore.

Python code is linted with ruff:

ruff check .

Deployment

The site is deployed automatically via GitHub Actions on pushes to main and on release tags. Versioned deployments are managed with mike, and the live site is hosted at https://docs.vaccel.org.

License

This work is licensed under CC BY-SA 4.0. See LICENSE for the full text.