Add ADR section to the generated docs

Makefile

@@ -12,15 +12,21 @@ install i:
 tidy pretty format f:
 	./mvnw formatter:format
 
-.PHONY: docs watch-docs
+##
+## Build the documentation and deploy it to the gh-pages branch. The
+## documentation is built using VitePress for the main site and Maven Javadoc
+## for the API documentation. Local development of the documentation can be done
+## using `make docs-dev`, which will start a local VitePress server.
+##
+.PHONY: docs docs-dev
 docs:
 	npm run docs:build
 	mvn javadoc:javadoc
 	cp -R target/site/apidocs xdocs/.vitepress/dist/
 	npm run deploy-docs
 
-watch-docs:
-	mvn asciidoctor:http
+docs-dev:
+	npm run docs:dev
 
 .PHONY: ui
 ui: ui/query-response-ui.jar

xdocs/.vitepress/config.mjs

@@ -16,6 +16,7 @@ export default defineConfig({
       { text: "Home", link: "/" },
       { text: "Guide", link: "/guide/what-is-query-response" },
       { text: "Reference", link: "/reference/developers-reference" },
+      { text: "ADR", link: "/adr/adrs"}
     ],
     sidebar: [
       {

docs/ADR-000-TEMPLATE.adoc → xdocs/adr/ADR-000-TEMPLATE.md

@@ -1,18 +1,18 @@
-= Title
+# Title
 
-== Status
+## Status
 
 What is the status, such as proposed, accepted, rejected, deprecated,
 superseded, etc.?
 
-== Context
+## Context
 
 What is the issue that we're seeing that is motivating this decision or change?
 
-== Decision
+## Decision
 
 What is the change that we're proposing and/or doing?
 
-== Consequences
+## Consequences
 
 What becomes easier or more difficult to do because of this change?

docs/ADR-001-builder-beans.adoc → xdocs/adr/ADR-001-builder-beans.md

@@ -1,30 +1,30 @@
-= Builder Beans
+# Builder Beans
 
-== Status
+## Status
 
 Accepted.
 
-== Context
+## Context
 
-There's an idiomatic way of providing library functionality throughout Spring.
-Modules such as Spring JDBC, AMQP or Web provide _templates_ as beans. Users
-can have these templates injected into their components, and access the
+There's an idiomatic way of providing library functionality throughout Spring.  
+Modules such as Spring JDBC, AMQP or Web provide *templates* as beans. Users  
+can have these templates injected into their components, and access the  
 functionality.
 
-Publishing the Query/Response API through static factory methods, may be
-convenient but **it is not the common way.** It also hides the capabilities
-of _mock_ or _test dummy_ setup in the user code, which makes testing harder.
+Publishing the Query/Response API through static factory methods may be  
+convenient but **it is not the common way.** It also hides the capabilities  
+of *mock* or *test dummy* setup in the user code, which makes testing harder.
 
-== Decision
+## Decision
 
-The `QueryBuilder` and `ResponseBuilder` should both be made available through
+The `QueryBuilder` and `ResponseBuilder` should both be made available through  
 the means of bean injection. The static factory methods are removed.
 
 The beans shall be available as mockable types, to better support testing.
 
-== Consequences
+## Consequences
 
-A lot of complexity caused by static access to the registry beans, will
+A lot of complexity caused by static access to the registry beans will  
 disappear.
 
 The convenient and very terse static API is no longer available.

xdocs/adr/adrs.md

@@ -0,0 +1,32 @@
+# Architecture Decision Records (ADR)
+
+Architecture Decision Records provide a way to document the decisions
+made in the architecture of a system. They help in understanding the context, 
+decision-making process, and consequences of architectural choices.
+
+## Accepted ADRs
+
+The following ADRs have been accepted and are part of the project's architecture
+documentation:
+
+- [ADR-001-builder-beans](./ADR-001-builder-beans)
+
+## Template for new ADRs
+
+The [ADR-000-TEMPLATE.md](ADR-000-TEMPLATE.md) provides a structured format for 
+documenting decisions. It includes sections for the title, status, context, 
+decision, and consequences.
+
+## Add a new ADR
+
+1. Create a new PR by branching off the `main` branch, naming it
+   `adr/XXX-title`, where `XXX` is the next available number and `title` is a
+   very short description of the decision.
+
+2. Add a new ADR file in the `xdocs/adr` directory using the available template.
+   Ensure that the file follows the naming convention `ADR-XXX-title.md`, using
+   the same number as the branch name.
+
+3. Update the `xdocs/adr/adrs.md` file to include a link to the new ADR file.
+
+4. Submit the PR for review.