Components
The components inside each container.
py-doc: py-doc command
The py-doc command and Python package. Reads py-doc.yml, prepares the Markdown and starts every tool in the tool image.
| Component | Technology | Description |
|---|---|---|
| Analysis | Python, Git | Counts what documents hold, checks a project without building it, and compares versions by section. |
| Build pipeline | Python | Joins a document’s sources, expands includes, conditions and variables, and picks the template and the output name. |
| Build report | JSON schema | Records the tools, sources, outputs, diagrams and warnings of a build as JSON. |
| C4 integration | structurizr-cli, Structurizr Local | Reads Structurizr workspaces, writes chapters from the model, draws the views and runs the live editor. |
| Commands | 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 | PyYAML | Loads py-doc.yml and checks every key, so a mistake is an error that names its place. |
| Content generators | Python, entry points | Write Markdown from other sources before the build: glossaries, indexes, traceability, API references, diagram files, commands. |
| Diagram renderer | 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. |
| HTML deck | 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 | 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 | 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 | python-docx, python-pptx | Turn Word documents and PowerPoint decks into Markdown that builds again. |
| Linter | markdown-it-py, Vale | Checks the writing with the built-in rules, structure rules, markdownlint and Vale, and reports one list. |
| Live preview | 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. |
| Pandoc engine | 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 | 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 | Python | Starts a new project: py-doc.yml, a first document, a C4 model, templates and a site. |
| Site generator | pandoc, MkDocs, Astro | Writes a page per source file and the navigation for MkDocs or Astro + Starlight, then builds the site. |
| Tool runner | 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. |
View: Components
The modules of the py-doc command.
