Add a ADR section to project documentation

febus982 · febus982 · commit 6eab5e76bbca · 2024-01-11T10:58:34.000Z
Signed-off-by: Federico Busetti &lt;729029+febus982@users.noreply.github.com&gt;
diff --git a/.adr-dir b/.adr-dir
@@ -0,0 +1 @@
+docs/adr
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: docs docs-build
+.PHONY: docs docs-build adr
 
 containers:
 	# Use local UID to avoid files permission issues when mounting directories
@@ -79,5 +79,8 @@ check: typing test format lint
 docs:
 	poetry run mkdocs serve
 
+adr:
+	adr-viewer --serve --adr-path docs/adr
+
 docs-build:
 	poetry run mkdocs build
diff --git a/docs/.pages b/docs/.pages
@@ -0,0 +1,3 @@
+nav:
+  - Home: index.md
+  - ADR: adr
diff --git a/docs/adr/.pages b/docs/adr/.pages
@@ -0,0 +1 @@
+order: desc
diff --git a/docs/adr/0001-record-architecture-decisions.md b/docs/adr/0001-record-architecture-decisions.md
@@ -0,0 +1,19 @@
+# 1. Record architecture decisions
+
+Date: 2024-01-11
+
+## Status
+
+Accepted
+
+## 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).
diff --git a/docs/adr/summary.md b/docs/adr/summary.md
@@ -0,0 +1,3 @@
+# Summary
+
+TODO: Generate summary here
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -7,6 +7,16 @@ docs_dir: docs/
 repo_name: 'febus982/bootstrap-python-fastapi'
 repo_url: 'https://github.com/febus982/bootstrap-python-fastapi'
 
+plugins:
+  - search
+  - awesome-pages
+
+# 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
+
 theme:
   name: material
   features:
@@ -35,9 +45,6 @@ extra:
     - icon: fontawesome/brands/linkedin
       link: https://www.linkedin.com/in/federico-b-a0b78232
 
-nav:
-  - Home: index.md
-
 markdown_extensions:
   - pymdownx.details
   - pymdownx.blocks.admonition
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -66,6 +66,7 @@ strawberry-graphql = { version = "*", extras = ["debug-server", "fastapi"] }
 mkdocs = "*"
 mkdocs-material = "*"
 pymdown-extensions = "*"
+mkdocs-awesome-pages-plugin = "*"
 
 [build-system]
 requires = ["poetry-core"]

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+nav:`
	`2`	`+ - Home: index.md`
	`3`	`+ - ADR: adr`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Summary`
	`2`	`+`
	`3`	`+TODO: Generate summary here`