py-doc: Markdown technical documentation tools

py-doc turns Markdown technical documentation into Word (.docx) documents, PowerPoint (.pptx) decks, PDF, HTML and web sites (MkDocs or Astro + Starlight). It checks the writing and draws every common kind of diagram. It makes posters, with blocks for charts, scales, shapes, protocols and physics. It writes and draws C4 architecture documentation from Structurizr models, imports Word and PowerPoint files, and builds whole sets of documents from one py-doc.yml. It replaces three earlier tools (py-doc2docx, py-doc2slides, py-doclint) and the createdocs build files from markbac/technical-documentation.

Pandoc writes every output, and it runs in a container with every other tool, so only Python and Docker need installing. The linter reads the Markdown with its own parser.

The user guide, requirements and architecture are published at https://markbac.github.io/py-doc/, built by py-doc itself (.github/workflows/pages.yml).

Important: Docker is required for every conversion. On Windows that is Docker Engine in WSL 2, which py-doc setup installs.

Commands

Command	What it does
py-doc init	Start a project: py-doc.yml, a first document, and optionally a C4 model, templates and a site
py-doc new	Start a legacy document, or number an existing Markdown file, from doc-numbers.yml at the repository root
py-doc build	Build every document described in py-doc.yml (generators, lint, documents, site), or one legacy createdocs file with --legacy
py-doc docx	Convert Markdown to Word, or with --watch rebuild on every save and serve a live HTML preview
py-doc slides	Convert Markdown to PowerPoint, or with -f html to an HTML deck with a presenter view; --watch shows the deck live
py-doc lint	Check writing style, glossary terms, acronyms, structure, links and project conventions; text, CSV, GitHub, JSON or SARIF
py-doc check	Check a project without building it: py-doc.yml, sources, templates, the site and lint
py-doc generate	Write the Markdown that content.generators makes: glossaries, indexes, traceability, API references
py-doc stats	Count the words, headings, tables, pictures and links of each document
py-doc diff	Compare two versions of documents section by section, or against a Git revision
py-doc c4	Check, export, draw and edit Structurizr workspaces (c4 up opens the live editor)
py-doc site	Make and build a web site of the documents with MkDocs or Astro + Starlight
py-doc poster	Build self-contained HTML posters from Markdown, and print them to PDF; --watch reloads them on every save
py-doc diagram	Draw one diagram, poster block or plot as an SVG, PNG, WebP or PDF file, or every one of a Markdown file; render_diagram() does the same from Python
py-doc icons	Download, list and search the icon packs that poster blocks draw with icon=
py-doc import	Convert a Word document or a PowerPoint deck to Markdown
py-doc template	Check and list the styles of a Word or PowerPoint template
py-doc tools, doctor, setup	Build and check the tool container, and install Docker Engine
py-doc migrate	Create py-doc.yml from legacy createdocs build files

The old commands py-doc2docx, py-doc2slides, py-doclint and py-c4-exporter still work and print a one-line note naming their replacement.

Install

git clone https://github.com/markbac/py-doc.git
cd py-doc
pip install -e .            # Python 3.10 or later
py-doc setup                # install Docker Engine (in the WSL distro on Windows) if you have not
py-doc tools build          # build the tool image (several GB, 5 to 30 minutes the first time)
py-doc doctor               # check that everything works

A few scientific fences (molecule, smith, plasmid and others) are drawn in an optional second image, the science image. It is built the first time a document uses one, or ahead of time with py-doc tools build --science.

On Windows, .\scripts\update.ps1 does all of that in a virtual environment of py-doc's own (.venv). Run .\scripts\update.ps1 after every pull: it installs any new dependencies, rebuilds the tool image when it changed, and checks that everything works.

Linux and Windows are supported. See Installation for the tool container, proxies and offline machines.

Quick start

py-doc init my-docs --name "Pump Controller" --c4 --site mkdocs -y
cd my-docs
py-doc check                                # the project and the writing, without building
py-doc build                                # build/overview.docx, build/architecture.docx, ...
py-doc c4 up architecture/workspace.dsl     # arrange the C4 views in Structurizr; Ctrl+C stops it
py-doc site build                           # site/build/index.html

While writing, py-doc docx guide.md --watch (or slides, or poster) builds on every save and keeps a live preview open in the browser, with every diagram drawn. The VS Code extension runs it for the open file and shows the preview beside the editor.

Documentation

py-doc documents itself with py-doc. The sources are in docs/, and the py-doc.yml at the root of this repository builds them: py-doc build for Word, HTML and PDF, py-doc site build for the web site.

• User guide: introduction, installation, projects and py-doc.yml, writing, outputs and templates, importing, C4 architecture, linting, web sites, reference, legacy build files and document numbers, generators, the build pipeline and analysis, posters, writing a poster, writing a document, writing a slide deck.
• Requirements: what py-doc must do and how well, with the status of every requirement and the open issues.
• Architecture: how py-doc is built, with C4 chapters generated from its Structurizr model, and the decisions behind it.
• Examples: a small project that uses every feature, with a command for each output.
• Bundle audit: notes on the original scripts.

Layout

src/
├── py_doc/
│   ├── app.py            # the py-doc command
│   ├── init.py           # py-doc init
│   ├── new.py            # py-doc new
│   ├── cli.py            # py-doc docx (and the old py-doc2docx)
│   ├── slides_cli.py     # py-doc slides (and the old py-doc2slides)
│   ├── _cli.py           # options, output paths, batch conversion and --watch shared by both
│   ├── convert.py        # DocxConverter and SlidesConverter, one file through pandoc, and its HTML preview twin
│   ├── config.py         # py-doc.yml model and validation
│   ├── build.py          # joins a document's sources and renders it
│   ├── directives.py     # includes, conditions and variables
│   ├── pandoc/           # the pandoc command, Word and PowerPoint finishing, Lua filters
│   ├── diagrams/         # diagram fences to pictures; poster blocks in documents (blocks.py); the written
│   │                     #   forms of the specialist fences (declarative.py) and their runners (tools/)
│   ├── c4/               # Structurizr workspaces: model, chapters, pictures, live editor
│   ├── site/             # web sites: pages, navigation, MkDocs and Starlight engines
│   ├── docx_import.py    # Word to Markdown
│   ├── pptx_import.py    # PowerPoint to Markdown
│   ├── runtime/          # the tool container: image, runner, doctor, setup; science/ is the optional science image
│   ├── markdown/         # parser and front matter, used by the linter
│   ├── lint/             # rules, structure rules, markdownlint, Vale, JSON and SARIF output
│   ├── generators/       # content generators and py-doc generate
│   ├── analysis/         # py-doc stats, check and diff
│   ├── migrate.py        # createdocs to py-doc.yml
│   ├── report.py         # the JSON build report
│   ├── poster*.py        # py-doc poster: the page, settings, themes and fonts (poster.py ...), the shared
│   │                     #   drawing core (poster_svg.py), maths (poster_math.py), the blocks (poster_blocks,
│   │                     #   poster_scales, poster_embedded, poster_shapes, poster_space) and plot (poster_plot.py)
│   ├── diagram_api.py    # render_diagram(): one diagram or block as SVG, PNG, WebP or PDF
│   ├── diagram_cli.py    # py-doc diagram, on diagram_api
│   ├── icons.py          # the icon packs of poster blocks; icons_cli.py is py-doc icons
│   ├── deck.py           # an HTML deck: the slides of a deck as one self-contained page
│   └── watch.py          # the --watch loop and preview server of poster, docx and slides
├── pydoc2docx/           # old import names, kept as aliases
├── pydoc2slides/
└── pydoclint/
editors/vscode/           # VS Code extension: the --watch live preview beside the editor
docs/                     # py-doc's own user guide, requirements and architecture
examples/                 # a project that uses every feature
tests/

Running tests

pip install -e ".[dev]"
python -m pytest
ruff check .
py-doc lint docs --strict
cd editors/vscode && npm ci && npm run lint && npm test   # the VS Code extension

CI runs on Linux and Windows with Python 3.14, the newest supported. Python 3.10, the oldest supported, is not tested in CI. macOS is not supported.

The tests run the tools on the host. So a second workflow, Tool image, builds the tool container and the science image, and draws every diagram type and the example posters with them. It runs when the image definition or the diagram code changes, every Monday, and by hand from the Actions tab.

License

Licensed under the MIT License.