Skip to content

Developer Guide

Prerequisites

  • uv — used for all Python dependency management and script execution
  • Python 3.14 (managed automatically by uv via .python-version)
  • Git

Clone and Install

git clone https://github.com/gooosetavo/dod-prohibited.git
cd dod-prohibited
uv sync

uv sync reads uv.lock and installs all dependencies into a local virtualenv. You don't need to activate it — prefix every command with uv run.

Generate the Docs

The site has two layers:

  1. Markdown content — generated by generate_docs.py from the live OPSS data source and SQLite database
  2. Static site — built by Zensical from those markdown files

Step 1 — Generate markdown

uv run python generate_docs.py

This fetches substance data, applies UNII/PubChem enrichment (if enabled), and writes all pages to docs/.

Step 2 — Build the site

uv run zensical build

Output goes to site/. This is what gets deployed to GitHub Pages.

Live Preview with Auto-Reload

Zensical's serve command watches docs/ and zensical.toml for changes and reloads the browser automatically:

uv run zensical serve

Open http://localhost:8000. Any edit to a file under docs/ or to zensical.toml triggers an instant rebuild and browser refresh — no manual restarts needed.

Typical dev loop

# Terminal 1 — serve with live reload
uv run zensical serve

# Terminal 2 — regenerate content, then watch the browser update
uv run python generate_docs.py

Edit a template or substance page in docs/, save, and the browser refreshes within a second.

Configuration

generate_docs.py exposes a Settings dataclass whose fields map 1-to-1 to DOD_-prefixed environment variables. Pass them inline or export before running.

Environment variable Default Description
DOD_USE_UNII_DATA true Enrich pages with FDA UNII database links
DOD_USE_PUBCHEM_DATA false Embed PubChem 3D conformer widgets (slower)
DOD_PUBCHEM_CACHE_DIR .cache/pubchem Local cache for PubChem JSON responses
DOD_INCLUDE_SEARCH_METADATA false Add auto-generated tag chips to frontmatter
DOD_LOG_LEVEL INFO Logging verbosity (DEBUG, INFO, WARNING, ERROR)
DOD_DB_FILE prohibited.db SQLite database path
DOD_SOURCE_URL OPSS URL Override the upstream data source

Examples

# Skip UNII fetching for a faster local run
DOD_USE_UNII_DATA=false uv run python generate_docs.py

# Enable PubChem widgets with debug logging
DOD_USE_PUBCHEM_DATA=true DOD_LOG_LEVEL=DEBUG uv run python generate_docs.py

Zensical Configuration

Site-level settings live in zensical.toml at the project root:

  • [project] — site name, extra CSS/JS assets
  • [project.theme] — color palette, Material features (navigation tabs, search, etc.)
  • [project.markdown_extensions] — enabled Python-Markdown extensions
  • nav — top-level navigation structure

Changes to zensical.toml are picked up immediately by uv run zensical serve.

Running Tests

# All tests
uv run pytest tests/ -v

# Specific file
uv run pytest tests/test_substance.py -v

# Unit tests only
uv run pytest tests/ -v -m unit

CI / GitHub Actions

The workflow in .github/workflows/update-site.yml runs on push to main and on a daily cron:

  1. check-for-changes — runs workflow_helper.py check-changes to detect substance additions/removals
  2. update-and-deploy — regenerates docs with DOD_USE_PUBCHEM_DATA=true, builds the site, and deploys to the gh-pages branch via peaceiris/actions-gh-pages

UNII and PubChem responses are cached between runs to avoid redundant downloads.