mkdocs-macros-adr-summary


Namemkdocs-macros-adr-summary JSON
Version 1.1.0 PyPI version JSON
download
home_pagehttps://febus982.github.io/mkdocs-macros-adr-summary
SummaryA plugin to generate a summary of a ADR directory
upload_time2024-12-15 18:24:40
maintainerNone
docs_urlNone
authorFederico Busetti
requires_python<3.14,>=3.9
licenseMIT
keywords adr architecture-decision-records mkdocs mkdocs-plugin mkdocs-macro mkdocs-macro-plugin nygard
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # 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

Raw data

            {
    "_id": null,
    "home_page": "https://febus982.github.io/mkdocs-macros-adr-summary",
    "name": "mkdocs-macros-adr-summary",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<3.14,>=3.9",
    "maintainer_email": null,
    "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/24/5d/d99b3653962ab5e0680faf5e739343e9eb83eb06b40922533ecbe0b57074/mkdocs_macros_adr_summary-1.1.0.tar.gz",
    "platform": null,
    "description": "# mkdocs-macros-adr-summary\n![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)\n[![Stable Version](https://img.shields.io/pypi/v/mkdocs-macros-adr-summary?color=blue)](https://pypi.org/project/mkdocs-macros-adr-summary/)\n[![stability-beta](https://img.shields.io/badge/stability-beta-33bbff.svg)](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)\n\n[![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)\n[![Maintainability](https://api.codeclimate.com/v1/badges/5631f62f6dcd3a34d7ae/maintainability)](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/5631f62f6dcd3a34d7ae/test_coverage)](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/test_coverage)\n\n[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)\n[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](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\nThe single ADR documents file names have to respect this format: `0000-my-decision-title.md`\n\n* start with 4 digits followed by the character `-`\n* the rest of the file name can contain only letters, numbers, dashes and underscores (`[A-Za-z0-9_-]` regex)\n* end with the `.md` extension\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      modules:\n        - 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\",m) }}\n```\n\nThe default template is:\n\n```markdown\n| ID | Date | Decision | Status |\n|----|------|----------|--------|\n{% for d in documents %}| {{ d.document_id }} | {{ d.date.strftime('%d-%m-%Y') if d.date else \"-\"}} | [{{ d.title }}]({{ d.file_path }}) | {{ d.status }}  |\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    document_id: Optional[int] = None\n    title: Optional[str] = None\n    date: Optional[date] = None\n    status: 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    | \u2705\ufe0e    |\n| status    | \u26a0      | \u2705\ufe0e    | \u2705\ufe0e    |\n| statuses  | \u2705\ufe0e     | \u26a0     | \u26a0     |\n| deciders  | \u274c      | \u2705\ufe0e    | \u2705\ufe0e    |\n| consulted | \u274c      | \u2705\ufe0e    | \u274c     |\n| informed  | \u274c      | \u2705\ufe0e    | \u274c     |\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* **MADR2** and **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* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md)\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": "1.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": "60c540511f5749ac97bfaa0188375f1b751008cb854bca6ddcd97dd9348ef4c7",
                "md5": "09e79f9c5f59099e52776a20f16fa7fe",
                "sha256": "4d2eb25f7e199222370d9bb9809be1feab2ab5379eb15d66d3772a257fd33ae8"
            },
            "downloads": -1,
            "filename": "mkdocs_macros_adr_summary-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "09e79f9c5f59099e52776a20f16fa7fe",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.14,>=3.9",
            "size": 20234,
            "upload_time": "2024-12-15T18:24:38",
            "upload_time_iso_8601": "2024-12-15T18:24:38.050521Z",
            "url": "https://files.pythonhosted.org/packages/60/c5/40511f5749ac97bfaa0188375f1b751008cb854bca6ddcd97dd9348ef4c7/mkdocs_macros_adr_summary-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "245dd99b3653962ab5e0680faf5e739343e9eb83eb06b40922533ecbe0b57074",
                "md5": "6a18a53d5f530d50f84b1e1fe7258bdd",
                "sha256": "6f2fb2c6f5085aa03d1b34206f35935641ff680fa3c5ede269477c5cd1602396"
            },
            "downloads": -1,
            "filename": "mkdocs_macros_adr_summary-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6a18a53d5f530d50f84b1e1fe7258bdd",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.14,>=3.9",
            "size": 10638,
            "upload_time": "2024-12-15T18:24:40",
            "upload_time_iso_8601": "2024-12-15T18:24:40.578494Z",
            "url": "https://files.pythonhosted.org/packages/24/5d/d99b3653962ab5e0680faf5e739343e9eb83eb06b40922533ecbe0b57074/mkdocs_macros_adr_summary-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-15 18:24:40",
    "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,
    "tox": true,
    "lcname": "mkdocs-macros-adr-summary"
}
Federico Busetti
Elapsed time: 0.34990s