Development and code map¶

This page is for contributors changing prodockit's Python package, tests, or documentation. Installing prodockit from PyPI is covered under Get started; this editable installation creates a development environment that keeps the checkout connected to the environment.

Create a development environment¶

Use the complete sequence for your platform. Each tab clones the repository, enters the checkout, creates and activates a dedicated Python 3.14 virtual environment, and installs the checkout in editable mode.

macOS Windows PowerShell Linux (Ubuntu)

git clone https://github.com/buckwem/prodockit-extensions.git
cd prodockit-extensions
"$(brew --prefix python@3.14)/bin/python3.14" -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-test.txt

git clone https://github.com/buckwem/prodockit-extensions.git
Set-Location prodockit-extensions
py -3.14 -m venv .venv
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-test.txt

git clone https://github.com/buckwem/prodockit-extensions.git
cd prodockit-extensions
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-test.txt

The editable install provides prodockit, pdk, and Zensical while importing package code directly from src/.

On macOS, expose Homebrew's Pango libraries

WeasyPrint's Python package still needs the native libraries installed by brew install pango. Export DYLD_FALLBACK_LIBRARY_PATH in the same terminal before running the PDF-backed tests:

export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix)/lib${DYLD_FALLBACK_LIBRARY_PATH:+:$DYLD_FALLBACK_LIBRARY_PATH}"

brew --prefix selects the correct Homebrew location on both Apple Silicon and Intel Macs and the rest preserves any fallback path already set.

Without it, tests that import or invoke WeasyPrint fail with cannot load library 'libgobject-2.0-0', even when Pango is installed. This is an environment problem rather than a regression in the PDF feature named by the failing test.

Run the ordinary contributor gates before opening a pull request:

ruff check .
mypy src
prodockit pins --check --offline
pytest
zensical build --clean --strict

Find the code¶

This source code map shows where each public feature is implemented.

src
- prodockit
  - cli.pypublic commands and aliases
  - settings.pyextension configuration helpers
  - headings.pyheading ids and numbering
  - refs.pyheading, figure, and table references
  - citations.pyMarkdown-defined citations
  - glossary.pyacronyms and glossary terms
  - bibliography.pyPandoc citeproc integration
  - tables.pytable layout attributes
  - tree.pydirectory-tree block
  - steps.pynumbered-steps block
  - index.pyinline index markers
  - shared_files.pypackaged managed styles and shared-file checks
  - template_sync.pytemplate updates and managed-style safeguards
  - pdfPDF build and source-bundle pipeline
  - bootstrapmachine setup stages and host model
  - testingpytest plugin, fixtures, and output checks
testsunit, integration, documentation, and built-output tests
docspublic guides and contributor internals
toolsMermaid and MathJax tooling used by PDF builds
pyproject.tomlpackage metadata, dependencies, and extension entry points
zensical.tomlthis documentation site's configuration

Stylesheet delivery code map¶

Managed styles cross the documentation, package, maintenance commands, and renderers. Use Table 47.1 when changing that contract:

1. Stylesheet delivery code map

Path	Responsibility
`docs/stylesheets/pdk.css`	Canonical website and shared PDF component defaults
`docs/stylesheets/pdk-pdf.css`	Canonical PDF-only presentation defaults
`docs/stylesheets/extra.css` and `print.css`	This site's author-owned overrides; never packaged as shared files
`pyproject.toml`	`force-include` mappings that place the two managed files under `prodockit/assets/` in a wheel
`src/prodockit/shared_files.py`	Finite resource inventory used by `pins` and `shared-files`
`src/prodockit/template_sync.py`	Detection and preservation of locally edited managed stylesheets
`src/prodockit/pdf/config.py`	Website and PDF stylesheet loading order used by PDF builds
`tests/test_shared_files.py` and `tests/test_shared_file_wheel.py`	Source, manifest, installed-wheel, and byte-for-byte delivery checks
`tests/test_template_sync.py`	Managed-style warning and preservation behaviour
`tests/test_pdf_config.py` and `tests/test_site_consistency.py`	Cascade order and reference-site configuration

The author-facing ownership and override rules are in Stylesheets; the contributor release obligations are in Extension integration.

Each Markdown extension is registered in pyproject.toml. A new public extension normally needs its module, entry point, tests, Authoring reference page, navigation entry, README inventory entry, and release note.

Call maintenance logic from Python¶

CLI commands should remain thin wrappers around functions that return useful state. For example, prodockit sync-repo calls sync_repo_metadata():

from prodockit.sync_repo import sync_repo_metadata

result = sync_repo_metadata(check=True)
if result.changed:
    print("out of date:", ", ".join(result.changes))

The function returns changes and notes instead of printing them, which keeps it usable from tests and other tooling. The CLI owns terminal formatting and exit status.

Keep the pytest plugin lightweight¶

The prodockit.testing pytest plugin is discovered in every environment where prodockit is installed, including unrelated test suites. It therefore avoids heavy imports at module import time. PyMuPDF, Beautiful Soup, and Zensical are loaded only inside fixtures that need them, and a missing zensical.toml affects the requested fixture rather than test collection.

When adding a fixture, preserve session scope where possible, prefix its name with prodockit_, resolve paths from pytest's root directory, and avoid work until a test requests it.