SDBS

General Purpose SSCCS Technical Documentation Build System

• A high-level orchestration layer for docs generation solutions (currently Quarto-driven).

Quick Start

With pip

pip install sdb
sdb init docs
sdb build docs --website

With Docker

docker pull ghcr.io/ssccsorg/sdbs:latest
docker run --rm -v $(pwd)/docs:/work -w /work ghcr.io/ssccsorg/sdbs:latest sdb build docs --website

Try the example project

git clone https://github.com/ssccsorg/sdbs.git
cd sdbs
./examples/build.sh quickstart

This installs SDBS from source (or uses Docker if Quarto is not available) and builds the examples/quickstart/ project — a minimal documentation site with a landing page, a getting-started guide, and an API reference.

CLI Reference

# Scaffold a new docs directory with default templates
sdb init docs

# Scaffold with SSCCS-specific templates
sdb init docs --template ssccs

# Build all targets
sdb build .

# Build with website profile (parallel)
sdb build . --website -j 4

# Validate links and citations
sdb check .

# Resolve broken paths and includes
sdb resolve .

Build Artifacts

When SDBS builds a documentation project, it produces and manages several directories. Understanding them helps with debugging and CI caching:

_site/

The final rendered website output. Contains the complete HTML site generated by Quarto when building with the --website flag. This is the directory that gets deployed to production. Cleaned and regenerated on each build.

_cached/

SDBS's hash-based render cache, stored in the project root (parent of docs/). Each target's rendered artifacts are keyed by the SHA-256 hash of its source QMD file and all its dependencies (includes, code cell dependencies, config files, bibliography, CSL).

On subsequent builds, if the hash matches a cached entry, the cached artifact is copied back instead of re-rendering. Cache entries for deleted or renamed targets are automatically cleaned up.

Structure:

_cached/
  target-name/
    <64-char-sha256>/
      target-name.pdf
      target-name.html
      target-name.c2pa      (if C2PA signing is enabled)
      site/                 (cached _site directory for website mode)

_jupyter_cache/

Jupyter kernel execution cache for Python code cells in QMD files. Managed by the jupyter-cache library. Avoids re-executing code cells when the cell source has not changed. Stored in the project root so it persists across builds and is sharable across parallel renders.

_llms/

LLM-friendly documentation index, generated by the post_render step. Contains a structured llms.txt (per the llmstxt.org standard) and *.llms.md files — Markdown extracts of each page without Quarto's HTML chrome. These files are consumed by AI agents for context retrieval.

Files in _llms/ are excluded from the Quarto build target discovery (via build.yml exclude patterns) and are not rendered themselves.

Other temporary directories

Directory	Purpose
_docsbuild/	Temporary isolated copies of docs/ for parallel website rendering. Deleted after build.
*_files/, *_output/, *_libs/, *_extensions/	Quarto-generated per-target directories containing figure files, intermediate outputs, and library assets.
_pages/	Snapshot of _site/ prepared for GitHub Pages deployment.

Development

Setup

git clone https://github.com/ssccsorg/sdbs.git
cd sdbs
pip install -e .

Run tests

python -m pytest tests/ -v

Build the Docker image

docker build -t ghcr.io/ssccsorg/sdbs:latest .

License

Apache 2.0