Introduction

py-doc turns Markdown technical documentation into Word documents, PowerPoint decks, PDF, HTML and web sites. It checks the writing, draws diagrams of every common kind, writes and draws C4 architecture documentation from Structurizr models, and imports Word and PowerPoint files into Markdown. One py-doc.yml describes every document of a project.

This guide is for the people who write and build documentation with py-doc. The requirements say what py-doc must do, and the architecture describes how it does it. py-doc builds all three documents itself, from the py-doc.yml at the root of its repository.

What py-doc does

Command	What it does
py-doc init	Starts a project: py-doc.yml, a first document, and optionally a C4 model, templates and a site
py-doc new	Starts a legacy document, or numbers an existing Markdown file, from doc-numbers.yml at the repository root
py-doc build	Builds every document described in py-doc.yml, after its generators and, on request, lint, and then the site
py-doc docx	Converts Markdown files to Word
py-doc slides	Converts Markdown files to PowerPoint, or to an HTML deck with -f html
py-doc lint	Checks writing style, glossary terms, acronyms, structure, links and project conventions
py-doc check	Checks a project without building it
py-doc generate	Writes the Markdown that the content generators make
py-doc diagram	Draws one diagram or poster block as an SVG, PNG, WebP or PDF file, or every one of a Markdown file
py-doc icons	Downloads, lists and searches the icon packs of poster blocks
py-doc stats	Counts the words, headings, tables, pictures and links of each document
py-doc diff	Compares two versions of documents section by section
py-doc c4	Checks, exports, draws and edits Structurizr workspaces
py-doc site	Makes and builds a web site of the documents with MkDocs or Astro + Starlight
py-doc poster	Builds self-contained HTML posters from Markdown, and prints them to PDF
py-doc import	Converts a Word document or a PowerPoint deck to Markdown
py-doc template	Checks and lists the styles of a Word or PowerPoint template
py-doc tools, doctor, setup	Builds and checks the tool container, and installs Docker Engine
py-doc migrate	Creates py-doc.yml from legacy createdocs build files

Pandoc writes every output, and it runs in a container with every other tool, so only Python and Docker need installing. The linter reads Markdown with a parser of its own, so code, links and front matter are never checked as prose.

How the guide is organised

1. Installation: Python, Docker and the tool container.
2. Projects: py-doc init, py-doc.yml and py-doc build.
3. Writing: the Markdown py-doc reads, callouts, captions, includes, conditions, variables and diagrams.
4. Outputs: Word, PowerPoint, PDF and HTML, templates and the build report.
5. Importing: Word documents and PowerPoint decks to Markdown.
6. C4 architecture: Structurizr models, generated chapters and the live editor.
7. Linting: the built-in rules, structure rules, markdownlint and Vale.
8. Web sites: MkDocs and Astro + Starlight.
9. Reference: the Python API, exit statuses and troubleshooting.
10. Legacy build files: createdocs build files, new documents, document numbers and migration.
11. Generators, the build pipeline and analysis: content generators, what py-doc build runs, and check, stats and diff.
12. Posters: every setting, block and theme of py-doc poster.
13. Writing a poster: a poster from a blank file to a printed page.
14. Writing a document: a technical document from an outline to a reviewed Word, PDF or HTML file.
15. Writing a slide deck: a PowerPoint deck in Markdown, with notes, columns and diagrams.

The examples

The examples folder of the repository is a small project that uses every feature: Markdown sources, a py-doc.yml, Word, PowerPoint, LaTeX and HTML templates, lint rules and a Structurizr workspace. Its README.md says which command makes which output.