DevKit Documentation

Sphinx documentation for the dsviper ecosystem: DSM language, Python API, Kibo code generator, and developer toolchain.

The generated HTML is served on the DevKit website.

Prerequisites

pip install -r requirements.txt

This installs Sphinx, the Furo theme, MyST parser, and dsviper (required by the pyi_signatures extension to extract API type hints from the installed package).

Build

make html          # macOS/Linux
make.bat html      # Windows

Output: build/html/index.html

Development

# Clean rebuild
make clean && make html

# Live preview with auto-rebuild
pip install sphinx-autobuild
sphinx-autobuild source build/html

Quality gates

make doctest    # run all `{doctest}` examples against the live dsviper runtime
make linkcheck  # validate every external URL
make coverage   # list dsviper symbols not referenced by autodoc/autosummary
make check      # run the three above; exits non-zero on first failure

make.bat exposes the same targets on Windows.

Distribution artifacts

make distzip    # build/dist/devkit-<version>-doc.zip — multi-page HTML archive
make pdf        # build/dist/devkit-<version>-doc.pdf — ~400-page PDF (xelatex)

DOC_VERSION defaults to 1.2; override from the environment if needed.

PDF prerequisites

The pdf target uses xelatex. Install a TeX distribution:

Platform	Recommended
macOS	BasicTeX + tex-gyre + gnu-freefont (Homebrew)
Linux	TeX Live (texlive-xetex, texlive-fonts-extra)
Windows	MiKTeX — auto-installs missing packages on first run, or TeX Live for Windows

Structure

devkit-doc/
├── source/
│   ├── conf.py           # Sphinx configuration
│   ├── index.rst         # Main page
│   ├── _ext/             # Custom extensions (DSM lexer, .pyi signatures)
│   ├── _static/          # CSS overrides
│   ├── _templates/       # Autosummary templates
│   ├── concepts/         # Viper architecture and design
│   ├── dsm/              # DSM language reference
│   ├── python/           # Python guide + API reference
│   └── tools/            # Toolchain (Kibo, dsm_util, IDE, templates)
├── Makefile              # macOS/Linux
├── make.bat              # Windows
└── requirements.txt      # Python dependencies

Custom Extensions

dsm_lexer

Pygments lexer for DSM syntax highlighting in code blocks.

pyi_signatures

Extracts type hints from the installed dsviper package (.pyi stub file) and injects them into autodoc-generated API documentation. Supports inheritance lookup.