A plugin to generate a summary of a ADR directory
Project description
mkdocs-macros-adr-summary
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 itemstatuses
. (I don't believe we should use multiple statuses, howeveradr-tools
allows it)deciders
,consulted
andinformed
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.
- 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.
Supported ADR formats
The supported ADR formats are:
nygard
format, it is recommended to use adr-tools to manage the directoryMADR
version 3MADR
version 2
Commands for development
All the common commands used during development can be run using make targets:
make dev-dependencies
: Install dev requirementsmake update-dependencies
: Update dev requirementsmake test
: Run test suitemake check
: Run tests, code style and lint checksmake fix
: Run code style and lint automatic fixes (where possible)make docs
: Render the mkdocs website locally
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_macros_adr_summary-1.0.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f1ee09fdea3b328af04c368a437e6e4de80de0e0961bb82c3f1b3baff8f73534 |
|
MD5 | 1f18ccdc94d5bda24720af84d66b878f |
|
BLAKE2b-256 | dd143d87adb79fb43a3cbf38535aaffd1a31f20edc551d9369a789b2f1d5b3b5 |
Hashes for mkdocs_macros_adr_summary-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b62f42568667d8a768fd57905cf845b10b2c31f0ece13e17e0e6e84a7869215d |
|
MD5 | a2dee3d3a411eadeb035b37e7fbbdfae |
|
BLAKE2b-256 | bd8e4f8906232a74367ef39be7f19f512078231879b4b5784a928e3913f55c32 |