| Analysis |
component |
Python, Git |
Counts what documents hold, checks a project without building it, and compares versions by section. |
| Author |
person |
|
Writes technical documentation in Markdown and builds it into Word, PowerPoint, PDF, HTML and web sites. |
| Build pipeline |
component |
Python |
Joins a document’s sources, expands includes, conditions and variables, and picks the template and the output name. |
| Build report |
component |
JSON schema |
Records the tools, sources, outputs, diagrams and warnings of a build as JSON. |
| C4 integration |
component |
structurizr-cli, Structurizr Local |
Reads Structurizr workspaces, writes chapters from the model, draws the views and runs the live editor. |
| Cache folders |
deploymentNode |
File system |
The user cache folder and the project’s .py-doc folder. |
| Caches |
container |
Files |
Diagram pictures (user cache folder), Structurizr exports, generated chapters and live preview pages (.py-doc in the project). |
| CI pipeline |
softwareSystem |
|
Runs the same build and lint commands on every change, such as GitHub Actions. |
| Commands |
component |
argparse |
Parses the command line and hands each command to its module: build, docx, slides, poster, lint, check, generate, stats, diff, c4, site, import, init, new, template, tools, doctor, setup, migrate. Runs the build pipeline around the documents. |
| Configuration |
component |
PyYAML |
Loads py-doc.yml and checks every key, so a mistake is an error that names its place. |
| Content generators |
component |
Python, entry points |
Write Markdown from other sources before the build: glossaries, indexes, traceability, API references, diagram files, commands. |
| Diagram renderer |
component |
Python |
Turns diagram fences, poster blocks, plots and the written forms of specialist fences into pictures with the right tool, and keeps them in a cache. |
| Docker Engine |
deploymentNode |
Docker Engine 27+ |
Runs every tool in a fresh container. |
| HTML deck |
component |
Python, JavaScript |
Makes a self-contained HTML deck of a deck’s slides, drawn by the poster engine, with navigation, a presenter view and a PDF of one slide a page. |
| Icons |
component |
Python, Iconify JSON |
The icon packs of poster blocks: downloaded once, checked and cached, with a project’s own icons, credits and a licence list. |
| Image command |
component |
Python |
py-doc diagram and render_diagram(): draw one diagram, poster block or plot as an SVG, PNG, WebP or PDF file, or every one of a Markdown file. |
| Importers |
component |
python-docx, python-pptx |
Turn Word documents and PowerPoint decks into Markdown that builds again. |
| Linter |
component |
markdown-it-py, Vale |
Checks the writing with the built-in rules, structure rules, markdownlint and Vale, and reports one list. |
| Live preview |
component |
Python, http.server |
With –watch, builds documents, decks and posters again on every save, writes an HTML twin of each document and deck, and serves the pages on 127.0.0.1 with a script that reloads them. |
| Package registries |
softwareSystem |
|
Docker Hub, GitHub releases, PyPI and npm: where the tool image and site builds download their tools. |
| Pandoc engine |
component |
pandoc, Lua, python-docx, python-pptx |
Runs pandoc with py-doc’s Lua filters, then finishes Word and PowerPoint files: templates, placeholders, captions, footers. |
| Poster builder |
component |
Python, segno, latex2mathml |
Makes a self-contained HTML poster from Markdown: its layout, themes, fonts, maths and native blocks, drawn as SVG and HTML. |
| Project scaffold |
component |
Python |
Starts a new project: py-doc.yml, a first document, a C4 model, templates and a site. |
| py-doc |
softwareSystem |
|
Turns Markdown into Word, PowerPoint, PDF, HTML and web sites, checks the writing, and documents C4 models. |
| py-doc command |
container |
Python 3.10+ |
The py-doc command and Python package. Reads py-doc.yml, prepares the Markdown and starts every tool in the tool image. |
| Python |
deploymentNode |
Python 3.10+ |
The py-doc package, installed with pip. |
| Reader |
person |
|
Reads the documents and sites that py-doc builds. |
| Science image |
container |
Docker image on the tool image |
Optional: the tool image with the scientific libraries some fences need, such as RDKit, matplotlib and CoolProp. Built the first time a fence needs it. |
| Site generator |
component |
pandoc, MkDocs, Astro |
Writes a page per source file and the navigation for MkDocs or Astro + Starlight, then builds the site. |
| Structurizr Local |
container |
Docker image structurizr/structurizr |
Shows a workspace in a browser to view it and arrange its views, and draws the pictures for documents. |
| Tool image |
container |
Docker image on Debian 12 |
Every program that is not Python: pandoc, XeLaTeX, PlantUML, Mermaid, Graphviz, the diagram tools, Chromium, structurizr-cli, Vale, markdownlint, MkDocs and Node. |
| Tool runner |
component |
Docker CLI, WSL |
Starts a program in a fresh container as the calling user, with only the folders it needs, and reports its whole output when it fails. |
| Visual Studio Code |
deploymentNode |
VS Code 1.75+ |
The author’s editor, with the py-doc extension installed from editors/vscode. |
| VS Code extension |
container |
JavaScript, js-yaml |
Starts the live preview (–watch) of the open file with the right command and shows it beside the editor. It draws no block itself. |
| Windows 11 or Linux |
deploymentNode |
Windows 11, Ubuntu, Debian |
The author’s computer. |
| Word and PowerPoint |
softwareSystem |
|
Open the built documents and decks, and are where documents start before py-doc imports them. |
| WSL 2 distro |
deploymentNode |
Ubuntu, Debian |
On Windows only: Docker Engine runs in Ubuntu or Debian under WSL 2. On Linux this level is not there. |