|
1 | | -# mkdocs-macros-adr-summary |
2 | | - |
3 | | - |
4 | | -[](https://pypi.org/project/mkdocs-macros-adr-summary/) |
5 | | -[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta) |
6 | | - |
7 | | -[](https://github.com/febus982/mkdocs-macros-adr-summary/actions/workflows/python-tests.yml) |
8 | | -[](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/maintainability) |
9 | | -[](https://codeclimate.com/github/febus982/mkdocs-macros-adr-summary/test_coverage) |
10 | | - |
11 | | -[](https://mypy-lang.org/) |
12 | | -[](https://github.com/psf/black) |
13 | | -[](https://github.com/charliermarsh/ruff) |
14 | | -[](https://github.com/PyCQA/bandit) |
15 | | - |
16 | | -This is a macro plugin to generates summaries from a list of a ADR documents in a directory. |
17 | | - |
18 | | -The single ADR documents file names have to respect this format: `0000-my-decision-title.md` |
19 | | - |
20 | | -* start with 4 digits followed by the character `-` |
21 | | -* the rest of the file name can contain only letters, numbers, dashes and underscores (`[A-Za-z0-9_-]` regex) |
22 | | -* end with the `.md` extension |
23 | | - |
24 | | -Examples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary) |
25 | | - |
26 | | -The package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version, |
27 | | -as soon as support for MADR version 2 has been implemented. Until that breaking changes can be introduced |
28 | | -and will be documented in the GitHub release description. |
29 | | - |
30 | | -## Quick start |
31 | | - |
32 | | -Enable the plugin in `mkdocs.yml` |
33 | | - |
34 | | -```yaml |
35 | | -plugins: |
36 | | - - macros: |
37 | | - modules: |
38 | | - - mkdocs_macros_adr_summary |
39 | | -``` |
40 | | -
|
41 | | -Create a markdown page in your mkdocs website and use the `adr_summary` macro providing |
42 | | -the path containing your ADR files relative to the `mkdocs.yml` file. |
43 | | - |
44 | | -``` |
45 | | -{% raw %} |
46 | | -{{ adr_summary(adr_path="docs/adr", adr_style="nygard") }} |
47 | | -{% endraw %} |
48 | | -``` |
49 | | -
|
50 | | -`adr_style` can be `nygard` or `MADR3` |
51 | | -
|
52 | | -## More customization |
53 | | -
|
54 | | -The page output is generated using a jinja template, but you can provide a custom one. The file path |
55 | | -must still be relative to the `mkdocs.yml` file. |
56 | | -
|
57 | | -``` |
58 | | -{% raw %} |
59 | | -{{ adr_summary(adr_path="docs/adr", adr_style="MADR3", template_file="other.jinja") }} |
60 | | -{% endraw %} |
61 | | -``` |
62 | | -
|
63 | | -The default template is: |
64 | | -
|
65 | | -``` |
66 | | -{% raw %} |
67 | | -| ID | Date | Decision | Status | |
68 | | -|----|------|----------|--------| |
69 | | -{% for d in documents %}| {{ d.document_id }} | {{ d.date.strftime('%d-%m-%Y') if d.date else "-"}} | [{{ d.title }}]({{ d.file_path }}) | {{ d.status }} | |
70 | | -{% endfor %} |
71 | | -{% endraw %} |
72 | | -``` |
73 | | -
|
74 | | -The `documents` variable in the jinja template is a Sequence of `ADRDocument` models: |
75 | | -
|
76 | | -```python |
77 | | -@dataclass |
78 | | -class ADRDocument: |
79 | | - file_path: str |
80 | | - document_id: Optional[int] = None |
81 | | - title: Optional[str] = None |
82 | | - date: Optional[date] = None |
83 | | - status: Optional[str] = None |
84 | | - statuses: Sequence[str] = tuple() |
85 | | - deciders: Optional[str] = None |
86 | | - consulted: Optional[str] = None |
87 | | - informed: Optional[str] = None |
88 | | -``` |
89 | | - |
90 | | -There are some differences in what metadata is available when using different formats: |
91 | | - |
92 | | -| | Nygard | MADR3 | MADR2 | |
93 | | -|-----------|--------|-------|-------| |
94 | | -| file_path | ✅︎ | ✅︎ | ✅︎ | |
95 | | -| title | ✅︎ | ✅︎ | ✅︎ | |
96 | | -| date | ✅︎ | ✅︎ | ✅︎ | |
97 | | -| status | ⚠ | ✅︎ | ✅︎ | |
98 | | -| statuses | ✅︎ | ⚠ | ⚠ | |
99 | | -| deciders | ❌ | ✅︎ | ✅︎ | |
100 | | -| consulted | ❌ | ✅︎ | ❌ | |
101 | | -| informed | ❌ | ✅︎ | ❌ | |
102 | | - |
103 | | -* **Nygard format** |
104 | | - * `status` is the last item `statuses`. (I don't believe we should use multiple |
105 | | - statuses, however `adr-tools` allows it) |
106 | | - * `deciders`, `consulted` and `informed` are not supported by the format |
107 | | -* **MADR2** and **MADR3** |
108 | | - * I wasn't able to find an automated tool supporting superseding documents. |
109 | | - By looking at the template it looks like there's a single status. |
110 | | - `statuses` will return a list with a single status. |
111 | | - |
112 | | -## Supported ADR formats |
113 | | - |
114 | | -The supported ADR formats are: |
115 | | -* `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory |
116 | | -* `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md) |
117 | | -* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md) |
118 | | - |
119 | | -## Commands for development |
120 | | - |
121 | | -All the common commands used during development can be run using make targets: |
122 | | - |
123 | | -* `make dev-dependencies`: Install dev requirements |
124 | | -* `make update-dependencies`: Update dev requirements |
125 | | -* `make test`: Run test suite |
126 | | -* `make check`: Run tests, code style and lint checks |
127 | | -* `make fix`: Run code style and lint automatic fixes (where possible) |
128 | | -* `make docs`: Render the mkdocs website locally |
| 1 | +--8<-- "./README.md" |
0 commit comments