# mkdocs-macros-adr-summary
[](https://pypi.org/project/mkdocs-macros-adr-summary/)
[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)
[](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml)
[](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-bandit.yml)
[](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/maintainability)
[](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/test_coverage)
[](https://mypy-lang.org/)
[](https://github.com/psf/black)
[](https://github.com/charliermarsh/ruff)
[](https://github.com/PyCQA/bandit)
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](https://febus982.github.io/mkdocs-macros-adr-summary)
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`
```yaml
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.
```markdown
{{ 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.
```markdown
{{ adr_summary(adr_path="docs/adr", adr_style="MADR3", template_file="other.jinja") }}
```
The default template is:
```markdown
## 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:
```python
@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](https://github.com/npryce/adr-tools) to manage the directory
* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)
Support for [MADR](https://adr.github.io/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
Raw data
{
"_id": null,
"home_page": "https://febus982.github.io/mkdocs-macros-adr-summary",
"name": "mkdocs-macros-adr-summary",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.13",
"maintainer_email": "",
"keywords": "adr,architecture-decision-records,mkdocs,mkdocs-plugin,mkdocs-macro,mkdocs-macro-plugin,nygard",
"author": "Federico Busetti",
"author_email": "729029+febus982@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/c0/7a/238100e2b7c65707d9b21fbbca2d5cd0ffd3f0782ef00a05db60f2294615/mkdocs_macros_adr_summary-0.1.0.tar.gz",
"platform": null,
"description": "# mkdocs-macros-adr-summary\n\n[](https://pypi.org/project/mkdocs-macros-adr-summary/)\n[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)\n\n[](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml)\n[](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-bandit.yml)\n[](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/maintainability)\n[](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/test_coverage)\n\n[](https://mypy-lang.org/)\n[](https://github.com/psf/black)\n[](https://github.com/charliermarsh/ruff)\n[](https://github.com/PyCQA/bandit)\n\nThis is a macro plugin to generates summaries from a list of a ADR documents in a directory.\n\nExamples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)\n\nThe package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version,\nas soon as support for MADR version 2 has been implemented. Until that breaking changes can be introduced\nand will be documented in the GitHub release description.\n\n## Quick start\n\nEnable the plugin in `mkdocs.yml`\n\n```yaml\nplugins:\n - macros:\n module_name: mkdocs_macros_adr_summary\n```\n\nCreate a markdown page in your mkdocs website and use the `adr_summary` macro providing\nthe path containing your ADR files relative to the `mkdocs.yml` file.\n\n```markdown\n{{ adr_summary(adr_path=\"docs/adr\", adr_style=\"nygard\") }}\n```\n\n`adr_style` can be `nygard` or `MADR3`\n\n## More customization\n\nThe page output is generated using a jinja template, but you can provide a custom one. The file path\nmust still be relative to the `mkdocs.yml` file.\n\n```markdown\n{{ adr_summary(adr_path=\"docs/adr\", adr_style=\"MADR3\", template_file=\"other.jinja\") }}\n```\n\nThe default template is:\n\n```markdown\n## Document list\n\n{% for d in documents %}\n* [{{ d.title }}]({{ d.filename }})\n * `{{ d.date.strftime('%d-%m-%Y') }}`\n * `{{ d.file_path }}`\n {% if d.statuses %}\n * Statuses:\n {% for status in d.statuses %}\n * {{ status }}\n {% endfor %}\n {% endif %}\n{% endfor %}\n```\n\nThe `documents` variable in the jinja template is a Sequence of `ADRDocument` models:\n\n```python\n@dataclass\nclass ADRDocument:\n file_path: str\n title: Optional[str] = None\n date: Optional[date] = None\n stasdetus: Optional[str] = None\n statuses: Sequence[str] = tuple()\n deciders: Optional[str] = None\n consulted: Optional[str] = None\n informed: Optional[str] = None\n```\n\nThere are some differences in what metadata is available when using different formats:\n\n| | Nygard | MADR3 | MADR2 |\n|-----------|--------|-------|-------|\n| file_path | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e |\n| title | \u2705\ufe0e | \u2705\ufe0e | \u2705\ufe0e |\n| date | \u2705\ufe0e | \u2705\ufe0e | TODO |\n| status | \u26a0 | \u2705\ufe0e | TODO |\n| statuses | \u2705\ufe0e | \u26a0 | TODO |\n| deciders | \u274c | \u2705\ufe0e | TODO |\n| consulted | \u274c | \u2705\ufe0e | TODO |\n| informed | \u274c | \u2705\ufe0e | TODO |\n\n* **Nygard format**\n * `status` is the last item `statuses`. (I don't believe we should use multiple\n statuses, however `adr-tools` allows it)\n * `deciders`, `consulted` and `informed` are not supported by the format\n* **MADR3**\n * I wasn't able to find an automated tool supporting superseding documents.\n By looking at the template it looks like there's a single status.\n `statuses` will return a list with a single status.\n\n## Supported ADR formats\n\nThe supported ADR formats are:\n* `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory\n* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)\n\nSupport for [MADR](https://adr.github.io/madr/) version 2 will be added in a future version.\n\n## Commands for development\n\nAll the common commands used during development can be run using make targets:\n\n* `make dev-dependencies`: Install dev requirements\n* `make update-dependencies`: Update dev requirements\n* `make test`: Run test suite\n* `make check`: Run tests, code style and lint checks\n* `make fix`: Run code style and lint automatic fixes (where possible)\n* `make docs`: Render the mkdocs website locally\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A plugin to generate a summary of a ADR directory",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://febus982.github.io/mkdocs-macros-adr-summary",
"Repository": "https://github.com/febus982/mkdocs-macros-adr-summary"
},
"split_keywords": [
"adr",
"architecture-decision-records",
"mkdocs",
"mkdocs-plugin",
"mkdocs-macro",
"mkdocs-macro-plugin",
"nygard"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "88e55ff2296908023fadcb87f38b471e3834a6efc5279d26c029f96491d1a206",
"md5": "2c206bed6e5176d0351b98bc2d27ce77",
"sha256": "ec7cc612d354a2c579425a6a16213e65ea284547194eb1b3f37e2c5e896d02c5"
},
"downloads": -1,
"filename": "mkdocs_macros_adr_summary-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c206bed6e5176d0351b98bc2d27ce77",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.13",
"size": 11016,
"upload_time": "2024-01-26T18:10:12",
"upload_time_iso_8601": "2024-01-26T18:10:12.272274Z",
"url": "https://files.pythonhosted.org/packages/88/e5/5ff2296908023fadcb87f38b471e3834a6efc5279d26c029f96491d1a206/mkdocs_macros_adr_summary-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c07a238100e2b7c65707d9b21fbbca2d5cd0ffd3f0782ef00a05db60f2294615",
"md5": "6d97816eec5255ebca815db161a1a506",
"sha256": "6b85aa928282038e61c1ed4418e2551fcda0f9182b6a5475779f9720ac61443c"
},
"downloads": -1,
"filename": "mkdocs_macros_adr_summary-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6d97816eec5255ebca815db161a1a506",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.13",
"size": 9430,
"upload_time": "2024-01-26T18:10:13",
"upload_time_iso_8601": "2024-01-26T18:10:13.921440Z",
"url": "https://files.pythonhosted.org/packages/c0/7a/238100e2b7c65707d9b21fbbca2d5cd0ffd3f0782ef00a05db60f2294615/mkdocs_macros_adr_summary-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-26 18:10:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "febus982",
"github_project": "mkdocs-macros-adr-summary",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-macros-adr-summary"
}
JSON
