Skip to content

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

git clone https://github.com/buckwem/prodockit-extensions
cd prodockit-extensions
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

On Windows, activate with .venv\Scripts\Activate.ps1. 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. On Apple Silicon, export DYLD_FALLBACK_LIBRARY_PATH in the same terminal before running the PDF-backed tests:

export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib

Without it, tests that import or invoke WeasyPrint fail with cannot load library 'libgobject-2.0-0', even when Pango is installed. On an Intel Mac, use /usr/local/lib instead.

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
      • 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

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.