mkdocs-decision-records 1.0.0__tar.gz

mkdocs_decision_records-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Timo Reymann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_decision_records-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.1
+Name: mkdocs-decision-records
+Version: 1.0.0
+Summary: Manage decision records with mkdocs in a customizable and minimal fashion.
+Author: Timo Reymann
+Author-email: mail@timo-reymann.de
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: mkdocs (>=1.6.1,<2.0.0)
+Requires-Dist: mkdocs-material (>=9.5.48,<10.0.0)
+Description-Content-Type: text/markdown
+
+mkdocs-decision-records
+==
+
+<p align="center">
+	<img width="600" src="https://raw.githubusercontent.com/timo-reymann/mkdocs-decision-records/main/.github/images/demo.png">
+    <br />
+    Manage decision records with mkdocs in a customizable and minimal fashion.
+</p>
+
+
+
+## Features
+
+- Customizable status colors and lifecycle
+- Enforces information to be present for ADRs
+- Allows description being kept as markdown
+
+## Installation
+
+1. Install `mkdocs-decision-records` from the PyPi registry using your favorite package manager
+2. Configure your `mkdocs.yml`
+   ```yaml
+   plugins:
+   - decision-records:
+       # Folder where your decision records are located, defaults to adr
+       decisions_folder: adr
+       # Optional prefix to prepend to ticket numbers
+       ticket_url_prefix: https://ticket.example.com/
+       # Configure amount of required deciders
+       required_deciders_count: 1
+       # Configure available stages and the badge colors
+       lifecycle_stages:
+         {status}: {color}
+   ```
+3. Create your ADRs ensuring to add the frontmatter meta data:
+   ```markdown
+   ---
+   id: 000
+   status: proposed | rejected | accepted | deprecated | … | superseded by
+   date: YYYY-MM-DD
+   deciders:
+      - decider 1
+      - decider 2
+   # Optional ticket
+   ticket: FOO-1
+   ---
+   ```
+
+## Motivation
+
+I love ADRs and documenting decisions in general. This plugin makes it a bit easier, enforcing basic meta information
+while keeping the format open enough so you can do your thing.
+
+## Contributing
+
+I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the configuration
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+To get started please read the [Contribution Guidelines](./CONTRIBUTING.md).
+
+## Development
+
+### Requirements
+
+- Python 3.12+
+- Poetry
+
+### Build
+
+````sh
+poetry install
+````
+
+### Alternatives
+
+- [mkdocs-material](https://pypi.org/project/mkdocs-material-adr/)
+    - Needs to use the theme
+    - ADR graph
+- [mkdocs-macros-adr-summary](https://github.com/febus982/mkdocs-macros-adr-summary)
+    - works entirely with macros
+    - no metadata table at the top

mkdocs_decision_records-1.0.0/README.md

@@ -0,0 +1,86 @@
+mkdocs-decision-records
+==
+
+<p align="center">
+	<img width="600" src="https://raw.githubusercontent.com/timo-reymann/mkdocs-decision-records/main/.github/images/demo.png">
+    <br />
+    Manage decision records with mkdocs in a customizable and minimal fashion.
+</p>
+
+
+
+## Features
+
+- Customizable status colors and lifecycle
+- Enforces information to be present for ADRs
+- Allows description being kept as markdown
+
+## Installation
+
+1. Install `mkdocs-decision-records` from the PyPi registry using your favorite package manager
+2. Configure your `mkdocs.yml`
+   ```yaml
+   plugins:
+   - decision-records:
+       # Folder where your decision records are located, defaults to adr
+       decisions_folder: adr
+       # Optional prefix to prepend to ticket numbers
+       ticket_url_prefix: https://ticket.example.com/
+       # Configure amount of required deciders
+       required_deciders_count: 1
+       # Configure available stages and the badge colors
+       lifecycle_stages:
+         {status}: {color}
+   ```
+3. Create your ADRs ensuring to add the frontmatter meta data:
+   ```markdown
+   ---
+   id: 000
+   status: proposed | rejected | accepted | deprecated | … | superseded by
+   date: YYYY-MM-DD
+   deciders:
+      - decider 1
+      - decider 2
+   # Optional ticket
+   ticket: FOO-1
+   ---
+   ```
+
+## Motivation
+
+I love ADRs and documenting decisions in general. This plugin makes it a bit easier, enforcing basic meta information
+while keeping the format open enough so you can do your thing.
+
+## Contributing
+
+I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the configuration
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+To get started please read the [Contribution Guidelines](./CONTRIBUTING.md).
+
+## Development
+
+### Requirements
+
+- Python 3.12+
+- Poetry
+
+### Build
+
+````sh
+poetry install
+````
+
+### Alternatives
+
+- [mkdocs-material](https://pypi.org/project/mkdocs-material-adr/)
+    - Needs to use the theme
+    - ADR graph
+- [mkdocs-macros-adr-summary](https://github.com/febus982/mkdocs-macros-adr-summary)
+    - works entirely with macros
+    - no metadata table at the top

mkdocs_decision_records-1.0.0/mkdocs_decision_records/_markdown_utils.py

@@ -0,0 +1,15 @@
+from collections.abc import Generator
+
+
+def _meta_table(items: list[tuple[str, str]]) -> Generator[str, None, None]:
+    yield "<table>"
+    for (h, v) in items:
+        yield f"<tr><td><strong>{h}</strong></td><td>{v}</td></tr>"
+    yield "</table>"
+
+
+def _list(items: list[str]) -> Generator[str]:
+    yield "<ul>"
+    for item in items:
+        yield f"<li>{item}</li>"
+    yield "</ul>"

mkdocs_decision_records-1.0.0/mkdocs_decision_records/plugin.py

@@ -0,0 +1,127 @@
+import re
+
+from mkdocs.config import config_options
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+from mkdocs_decision_records._markdown_utils import _list, _meta_table
+
+CONFIG_DECISIONS_FOLDER_KEY = "decisions_folder"
+CONFIG_TICKET_URL_PREFIX = "ticket_url_prefix"
+
+CONFIG_LIFECYCLE_COLORS_KEY = "lifecycle_stages"
+CONFIG_DECISIONS_FOLDER_DEFAULT = "adr"
+
+CONFIG_REQUIRED_DECIDERS_COUNT_KEY = "required_deciders_count"
+CONFIG_REQUIRED_DECIDERS_COUNT_DEFAULT = 1
+
+DR_TITLE_WITH_NUM = re.compile(r'\d{3,}.*')
+
+DEFAULT_LIFECYCLE_COLORS = {
+    "accepted": "#28a745",
+    "proposed": "gray",
+    "rejected": "#dc3545",
+    "deprecated": "#6c757d",
+    "superseded": "#17a2b8",
+}
+
+
+class InvalidMetaDataError(PluginError):
+    def __init__(self, page: Page, field: str, message: str):
+        self.field = field
+        self.raw_message = message
+        self.message = f"Invalid metadata for field '{field}' in {page.file.src_path}: {message}"
+
+
+def _require_meta(page: Page, field: str) -> any:
+    val = page.meta.get(field, None)
+    if val is None:
+        raise InvalidMetaDataError(page, field, "Required, but not set.")
+    return val
+
+
+class DecisionRecordsPlugin(BasePlugin):
+    config_scheme = (
+        (CONFIG_DECISIONS_FOLDER_KEY, config_options.Type(str, default=CONFIG_DECISIONS_FOLDER_DEFAULT)),
+        (CONFIG_TICKET_URL_PREFIX, config_options.Type(str, default=None)),
+        (CONFIG_LIFECYCLE_COLORS_KEY, config_options.Type(dict, default=DEFAULT_LIFECYCLE_COLORS)),
+        (CONFIG_REQUIRED_DECIDERS_COUNT_KEY, config_options.Type(int, default=CONFIG_REQUIRED_DECIDERS_COUNT_DEFAULT))
+    )
+
+    def on_page_markdown(self, markdown: str, page: Page, config: MkDocsConfig, files: Files):
+        if not page.file.src_path.startswith(self.config.get(CONFIG_DECISIONS_FOLDER_KEY)):
+            return markdown
+
+        title = page.meta.get("title", None) or page.title
+        dr_id = _require_meta(page, "id")
+
+        if dr_id == 0:
+            page.title = "000 - Template"
+            return markdown
+
+        meta = [
+            ("Status", self._create_status_badge(page)),
+            ("Date", _require_meta(page, "date")),
+        ]
+
+        deciders = page.meta.get("deciders", [])
+        if len(deciders) < self.required_deciders_count:
+            raise InvalidMetaDataError(page, "deciders",
+                                       f"At least {self.required_deciders_count} deciders are required for a decision")
+        elif len(deciders) > 0:
+            meta.append((
+                "Deciders" if len(deciders) > 1 else "Decider",
+                "\n".join(_list(deciders)) if len(deciders) > 1 else deciders[0],
+            ))
+
+        ticket = page.meta.get("ticket", None)
+        if ticket is not None:
+            if self.config.get(CONFIG_TICKET_URL_PREFIX) is not None:
+                ticket_text = f"<a href='{self.config.get(CONFIG_TICKET_URL_PREFIX)}/{ticket}'>{ticket.upper()}</a>"
+            else:
+                ticket_text = ticket.upper()
+
+            meta.append((
+                "Ticket",
+                ticket_text,
+            ))
+
+        meta_info = "\n".join(_meta_table(meta))
+
+        header = title if DR_TITLE_WITH_NUM.match(title) else f"{dr_id:03d} - {title}"
+        page.title = header
+
+        return (
+            f"{header}\n"
+            f"===\n"
+            f"{meta_info}\n"
+            f"{markdown}"
+        )
+
+    @property
+    def lifecycles(self) -> dict[str, str]:
+        configured_lifecycle_colors = self.config.get(CONFIG_LIFECYCLE_COLORS_KEY, None)
+        return {
+            **DEFAULT_LIFECYCLE_COLORS,
+            **configured_lifecycle_colors,
+        }
+
+    @property
+    def required_deciders_count(self):
+        return self.config.get(CONFIG_REQUIRED_DECIDERS_COUNT_KEY, CONFIG_REQUIRED_DECIDERS_COUNT_DEFAULT)
+
+    def _create_status_badge(self, page):
+        status = _require_meta(page, "status")
+
+        status_color = self.lifecycles.get(status, None)
+        if status_color is None:
+            raise InvalidMetaDataError(page, "status", f"Invalid status {status}")
+
+        return (
+            f"<span style='color: white;background:{status_color};padding:.4em;border-radius:8px;font-size:100%;'>"
+            f"{status}"
+            f"</span>"
+        )

mkdocs_decision_records-1.0.0/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "mkdocs-decision-records"
+version = "1.0.0"
+description = "Manage decision records with mkdocs in a customizable and minimal fashion."
+authors = ["Timo Reymann <mail@timo-reymann.de>"]
+readme = "README.md"
+include = ["mkdocs_decision_records"]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+mkdocs = "^1.6.1"
+mkdocs-material = "^9.5.48"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.plugins."mkdocs.plugins"]
+decision-records = "mkdocs_decision_records.plugin:DecisionRecordsPlugin"