Initial implementation (#1)

* Initial implementation supporting nygard ADR format and jinja template rendering

Signed-off-by: Federico Busetti <[email protected]>

.adr-dir

@@ -0,0 +1 @@
+docs/adr

Makefile

@@ -28,13 +28,13 @@ lint-fix:
 	poetry run ruff . --fix
 
 dev-dependencies:
-	poetry install --with dev --no-root
+	poetry install --with dev
 
 update-dependencies:
 	poetry update --with dev
 
 fix:  format-fix lint-fix
-check: typing format lint test bandit
+check: typing format lint bandit test
 
 docs:
 	poetry run mkdocs serve

README.md

@@ -1,7 +1,7 @@
 # mkdocs-macros-adr-summary
 ![Static Badge](https://img.shields.io/badge/Python-3.8_%7C_3.9_%7C_3.10_%7C_3.11_%7C_3.12-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-wip](https://img.shields.io/badge/stability-wip-lightgrey.svg)](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#work-in-progress)
+[![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)
 [![Bandit checks](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-bandit.yml/badge.svg?branch=main)](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-bandit.yml)
@@ -13,6 +13,76 @@
 [![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.
+
+Examples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)
+
+## 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
+# Summary
+
+{{ adr_summary(adr_path="docs/adr") }}
+```
+
+## 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
+# Summary
+
+{{ adr_summary(adr_path="docs/adr", 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 `document` variable in the jinja template is a Sequence of:
+
+```python
+@dataclass
+class ADRDocument:
+    file_path: str
+    title: str
+    date: Optional[date]
+    statuses: Optional[Sequence[str]]
+```
+
+## Supported ADR formats
+
+The only supported ADR format currently is the `nygard` format, it is recommended to
+use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory.
+
+Support for [MADR](https://adr.github.io/madr/) versions 2 and 3 will be added with future iterations.
+
 ## Commands for development
 
 All the common commands used during development can be run using make targets:

docs/.pages

@@ -0,0 +1,3 @@
+nav:
+  - Home: index.md
+  - ADR (Nygard format): adr

docs/adr/.pages

@@ -0,0 +1,5 @@
+order: desc
+
+nav:
+  - summary.md
+  - ...

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,21 @@
+# 1. Record architecture decisions
+
+Date: 2024-01-20
+
+## Status
+
+Superceded by [2. Supersedes 1](0002-supercedes-1.md)
+
+Superceded by [3. Supersedes 1-b](0003-supercedes-1-b.md)
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

docs/adr/0002-supercedes-1.md

@@ -0,0 +1,21 @@
+# 2. Supercedes 1
+
+Date: 2024-01-22
+
+## Status
+
+Accepted
+
+Supercedes [1. Record architecture decisions](0001-record-architecture-decisions.md)
+
+## Context
+
+The issue motivating this decision, and any context that influences or constrains the decision.
+
+## Decision
+
+The change that we're proposing or have agreed to implement.
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

docs/adr/0003-supercedes-1-b.md

@@ -0,0 +1,21 @@
+# 3. Supercedes 1-b
+
+Date: 2024-01-22
+
+## Status
+
+Accepted
+
+Supercedes [1. Record architecture decisions](0001-record-architecture-decisions.md)
+
+## Context
+
+The issue motivating this decision, and any context that influences or constrains the decision.
+
+## Decision
+
+The change that we're proposing or have agreed to implement.
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

docs/adr/summary.md

@@ -0,0 +1,3 @@
+# Summary
+
+{{ adr_summary(adr_path="docs/adr") }}

docs/index.md

@@ -1 +1,98 @@
 # mkdocs-macros-adr-summary
+
+![Static Badge](https://img.shields.io/badge/Python-3.8_%7C_3.9_%7C_3.10_%7C_3.11_%7C_3.12-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)
+[![Bandit checks](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-bandit.yml/badge.svg?branch=main)](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-bandit.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.
+
+Examples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)
+
+## 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.
+
+```
+{% raw %}
+{{ adr_summary(adr_path="docs/adr") }}
+{% endraw %}
+```
+
+## 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.
+
+```
+{% raw %}
+{{ adr_summary(adr_path="docs/adr", template_file="other.jinja") }}
+{% endraw %}
+```
+
+The default template is:
+
+```
+{% raw %}
+## 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 %}
+{% endraw %}
+```
+
+The `document` variable in the jinja template is a Sequence of:
+
+```python
+@dataclass
+class ADRDocument:
+    file_path: str
+    title: str
+    date: Optional[date]
+    statuses: Optional[Sequence[str]]
+```
+
+## Supported ADR formats
+
+The only supported ADR format currently is the `nygard` format, it is recommended to
+use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory.
+
+Support for [MADR](https://adr.github.io/madr/) versions 2 and 3 will be added with future iterations.
+
+## 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

mkdocs.yml

@@ -9,7 +9,10 @@ repo_url: 'https://github.com/febus982/mkdocs-macros-adr-summary'
 
 plugins:
   - search
+  - awesome-pages
   - mike
+  - macros:
+        module_name: mkdocs_macros_adr_summary
 
 theme:
   name: material
@@ -44,8 +47,11 @@ extra:
     provider: mike
     default: stable
 
-nav:
-  - Home: index.md
+# Do not use the nav section in this file but reference to the .pages files
+# in the docs/ directory and subdirectories (awesome-pages plugin)
+# https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin
+#nav:
+#  - Home: index.md
 
 markdown_extensions:
   - pymdownx.details

mkdocs_macros_adr_summary/__init__.py

@@ -1,5 +1,13 @@
-def some_function() -> str:
-    return "some_variable_to_test"
+from functools import partial
+
+from mkdocs_macros.plugin import MacrosPlugin
+
+from .plugin import adr_summary
+
+
+def define_env(env: MacrosPlugin) -> None:
+    # We could use the decorator here, but it would be more complex to test
+    env.macro(partial(adr_summary, env), "adr_summary")
 
 
 __version__ = "0.0.0"

mkdocs_macros_adr_summary/factory.py

@@ -0,0 +1,15 @@
+from typing import Dict, Type
+
+from .interfaces import ADRParser, ADRStyle
+from .parser import NygardParser
+
+parser_registry: Dict[ADRStyle, Type[ADRParser]] = {"nygard": NygardParser}
+
+
+def get_parser(adr_style: ADRStyle) -> Type[ADRParser]:
+    try:
+        parser = parser_registry[adr_style]
+    except KeyError:
+        raise ValueError(f"Format {adr_style} not supported")
+
+    return parser

mkdocs_macros_adr_summary/interfaces.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import date
+from enum import Enum
+from pathlib import Path
+from typing import Literal, Optional, Sequence
+
+ADRStyle = Literal["nygard"]
+
+
+class ADRFormat(Enum):
+    nygard = 1
+
+
+@dataclass
+class ADRDocument:
+    file_path: str
+    title: str
+    date: Optional[date]
+    statuses: Optional[Sequence[str]]
+
+
+class ADRParser(ABC):
+    @staticmethod
+    @abstractmethod
+    def parse(file_path: Path, base_path: Path) -> ADRDocument:
+        ...