Skip to main content

A plugin to generate a summary of a ADR directory

Project description

mkdocs-macros-adr-summary

Static Badge Stable Version stability-beta

Python tests Maintainability Test Coverage

Checked with mypy Code style: black Ruff security: bandit

This is a macro plugin to generates summaries from a list of a ADR documents in a directory.

The single ADR documents file names have to respect this format: 0000-my-decision-title.md

  • start with 4 digits followed by the character -
  • the rest of the file name can contain only letters, numbers, dashes and underscores ([A-Za-z0-9_-] regex)
  • end with the .md extension

Examples and documentation can be found here

The package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version, as soon as support for MADR version 2 has been implemented. Until that breaking changes can be introduced and will be documented in the GitHub release description.

Quick start

Enable the plugin in mkdocs.yml

plugins:
  - macros:
      modules:
        - mkdocs_macros_adr_summary

Create a markdown page in your mkdocs website and use the adr_summary macro providing the path containing your ADR files relative to the mkdocs.yml file.

{{ adr_summary(adr_path="docs/adr", adr_style="nygard") }}

adr_style can be nygard or MADR3

More customization

The page output is generated using a jinja template, but you can provide a custom one. The file path must still be relative to the mkdocs.yml file.

{{ adr_summary(adr_path="docs/adr", adr_style="MADR3",m) }}

The default template is:

| ID | Date | Decision | Status |
|----|------|----------|--------|
{% for d in documents %}| {{ d.document_id }} | {{ d.date.strftime('%d-%m-%Y') if d.date else "-"}} | [{{ d.title }}]({{ d.file_path }}) | {{ d.status }}  |
{% endfor %}

The documents variable in the jinja template is a Sequence of ADRDocument models:

@dataclass
class ADRDocument:
    file_path: str
    document_id: Optional[int] = None
    title: Optional[str] = None
    date: Optional[date] = None
    status: Optional[str] = None
    statuses: Sequence[str] = tuple()
    deciders: Optional[str] = None
    consulted: Optional[str] = None
    informed: Optional[str] = None

There are some differences in what metadata is available when using different formats:

Nygard MADR3 MADR2
file_path ✅︎ ✅︎ ✅︎
title ✅︎ ✅︎ ✅︎
date ✅︎ ✅︎ ✅︎
status ✅︎ ✅︎
statuses ✅︎
deciders ✅︎ ✅︎
consulted ✅︎
informed ✅︎
  • Nygard format
    • status is the last item statuses. (I don't believe we should use multiple statuses, however adr-tools allows it)
    • deciders, consulted and informed are not supported by the format
  • MADR2 and MADR3
    • I wasn't able to find an automated tool supporting superseding documents. By looking at the template it looks like there's a single status. statuses will return a list with a single status.

Supported ADR formats

The supported ADR formats are:

Commands for development

All the common commands used during development can be run using make targets:

  • make dev-dependencies: Install dev requirements
  • make update-dependencies: Update dev requirements
  • make test: Run test suite
  • make check: Run tests, code style and lint checks
  • make fix: Run code style and lint automatic fixes (where possible)
  • make docs: Render the mkdocs website locally

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_macros_adr_summary-1.0.0.tar.gz (10.7 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file mkdocs_macros_adr_summary-1.0.0.tar.gz.

File metadata

File hashes

Hashes for mkdocs_macros_adr_summary-1.0.0.tar.gz
Algorithm Hash digest
SHA256 f1ee09fdea3b328af04c368a437e6e4de80de0e0961bb82c3f1b3baff8f73534
MD5 1f18ccdc94d5bda24720af84d66b878f
BLAKE2b-256 dd143d87adb79fb43a3cbf38535aaffd1a31f20edc551d9369a789b2f1d5b3b5

See more details on using hashes here.

File details

Details for the file mkdocs_macros_adr_summary-1.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_macros_adr_summary-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b62f42568667d8a768fd57905cf845b10b2c31f0ece13e17e0e6e84a7869215d
MD5 a2dee3d3a411eadeb035b37e7fbbdfae
BLAKE2b-256 bd8e4f8906232a74367ef39be7f19f512078231879b4b5784a928e3913f55c32

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page