mkdocs-macros-adr-summary 0.1.0

A plugin to generate a summary of a ADR directory

mkdocs-macros-adr-summary

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

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:
        module_name: 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", template_file="other.jinja") }}

The default template is:

## Document list

{% for d in documents %}
* [{{ d.title }}]({{ d.filename }})
    * `{{ d.date.strftime('%d-%m-%Y') }}`
    * `{{ d.file_path }}`
    {% if d.statuses %}
    * Statuses:
        {% for status in d.statuses %}
        * {{ status }}
        {% endfor %}
    {% endif %}
{% endfor %}

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

@dataclass
class ADRDocument:
    file_path: str
    title: Optional[str] = None
    date: Optional[date] = None
    stasdetus: 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	✅︎	✅︎	TODO
status	⚠	✅︎	TODO
statuses	✅︎	⚠	TODO
deciders	❌	✅︎	TODO
consulted	❌	✅︎	TODO
informed	❌	✅︎	TODO

• 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
• 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:

• nygard format, it is recommended to use adr-tools to manage the directory
• MADR version 3

Support for MADR version 2 will be added in a future version.

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