Metadata-Version: 2.3
Name: mkdocs-macros-adr-summary
Version: 1.1.1
Summary: A plugin to generate a summary of a ADR directory
License: MIT
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
Requires-Python: >=3.9,<3.14
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: mistune (>=3.0.2,<3.1)
Requires-Dist: mkdocs (>=1.4.3,<2.0.0)
Requires-Dist: mkdocs-macros-plugin (>=1.0.5,<2.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Project-URL: Homepage, https://febus982.github.io/mkdocs-macros-adr-summary
Project-URL: Repository, https://github.com/febus982/mkdocs-macros-adr-summary
Description-Content-Type: text/markdown

# mkdocs-macros-adr-summary
![Static Badge](https://img.shields.io/badge/Python-3.9_%7C_3.10_%7C_3.11_%7C_3.12_%7C_3.13-blue?logo=python&logoColor=white)
[![Stable Version](https://img.shields.io/pypi/v/mkdocs-macros-adr-summary?color=blue)](https://pypi.org/project/mkdocs-macros-adr-summary/)
[![stability-beta](https://img.shields.io/badge/stability-beta-33bbff.svg)](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)

[![Python tests](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml/badge.svg?branch=main)](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml)
[![Maintainability](https://api.codeclimate.com/v1/badges/5631f62f6dcd3a34d7ae/maintainability)](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/5631f62f6dcd3a34d7ae/test_coverage)](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/test_coverage)

[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)
[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/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](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:
      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.

```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",m) }}
```

The default template is:

```markdown
| 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:

```python
@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:
* `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)
* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md)

## 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

