Skip to content

Documentation as Code

Documentation as Code (DaC) applies software development practices to documentation. In Python projects, this approach can integrate with GitHub to automatically generate and host user guides as secure web pages.

Prominent open-source projects utilizing this documentation strategy include:

Project Description
Pydantic Fast and extensible data validation
FastAPI Web framework for building APIs
Prefect Dataflow automation platform
Ruff Extremely fast Python linter and formatter
isort Python utility / library to sort imports
commitizen Create committing rules for projects
pre-commit Framework for managing multi-language pre-commit hooks
FastMCP Framework for building Model Context Protocol servers
prek Fast, drop-in replacement for pre-commit

These examples demonstrate robust CI/CD implementations for contemporary Python projects.

Tip

Check out the automated website for this repo.

Overview

In this template:

  • API reference documentation is compiled directly from the source code.
  • Because of this, comprehensive and accurate docstrings are critical.
  • A CI/CD pipeline utilizes zensical to build a static website from the source code and then deploys it to GitHub Pages.
  • To use a custom domain, a CNAME record must point to the resulting GitHub Page.

Tip

GitHub Enterprise supports access control; if configured, it will challenge clients for authentication even when using public domains with GitHub Pages.

Types of Documentation

For a comprehensive breakdown of documentation types, refer to this guide. Many languages include native or third-party tooling for generating API documentation automatically.

Consider the project shown below:

📁 ${namespace}/
└── 📁 ${package}/
    ├── 📄 ...
    ├── 📁 cli/
    │   ├── 📄 load
    │   ├── 📄 truncate
    │   └── 📄 ...
    ├── 📁 elt/
    │   ├── 📄 pipelines
    │   ├── 📄 connectors
    │   ├── 📄 transforms
    │   └── 📄 ...
    └── 📁 utils/
        ├── 📄 logging
        ├── 📄 tensor_calculus
        └── 📄 ...

Important

A systematically structured project naturally facilitates high-quality API documentation by organizing components logically.

Leveraging clear naming conventions, predictable signatures, standard docstrings, module-level overviews, and embedded examples significantly reduces the burden of writing decoupled, manually maintained user guides.

Why Documentation as Code?

Tip

Defining documentation in a separate system often leads to neglect, resulting in outdated information that confuses users and increases technical debt.

Maintaining documentation alongside the code encourages developers to update it simultaneously. Documentation as Code solutions organize this workflow by automating the generation and deployment of these updates.

(Swimm)

Key benefits include:

  • Improved efficiency
  • Greater completeness
  • Simplified maintenance
  • Enhanced collaboration
  • Automated generation
  • Synchronized versioning

Generating API Reference Documentation

The primary focus for this template is technical API reference documentation.

Across programming languages, the standard approach revolves around writing structured comments (e.g., docstrings for modules, functions, and objects). A DaC framework then parses the source code to generate a static web page:

---
title: Documentation as Code
config:
  theme: 'dark'
---
%%{init: {"flowchart": {"htmlLabels": false}} }%%
flowchart LR
  source-code["Source Code + Comments (docstrings)"]
    --> dac-framework["DaC Framework"]
    --> static-webpage["Static Web Page (HTML + JS + Assets)"]

Frameworks

The most common Python DaC frameworks, sorted by comparative complexity are:

Framework Complexity Primary Use Case
pdoc LOW API Documentation
mkdocs MEDIUM API Documentation and Tutorials
zensical MEDIUM Extended mkdocs implementation
Sphinx HIGH Extensive, complex documentation

GitHub Actions

The action-docs project enables DaC for custom GitHub Actions by automatically updating templated Markdown files.

We also leverage mkdocstrings-github to generate live docs for CI/CD templates.

See the CI/CD guide for additional information.

Terraform

The terraform-docs project provides DaC for custom Terraform Modules by managing templated Markdown files.

The project also provides an official GitHub Action, available here.

Interfaces

Many applications natively provide external control interfaces, most commonly:

  • Command-line Interfaces (CLIs)
  • Web Application Programming Interfaces (Web APIs)

Some application frameworks can automatically generate and serve end-user documentation for these interfaces:

Typically, these frameworks leverage Python "type hints" to generate rich documentation alongside their core functionality.

Tip

While alternatives exist, the above are currently among the most robust Python-based solutions for these use cases.

Hosting with GitHub Pages

To use a custom domain, create a CNAME record pointing to ${github_org | github_user}.github.io.

Then, configure GitHub Pages in the repository configuration (repository admin rights are required):

GitHub Pages - Settings