Add docstring build task

Runs a Clojure script to add docstrings from Duct libraries into the
documentation.

Author: weavejester

.github/workflows/asciidoc.yml

@@ -18,11 +18,15 @@ jobs:
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
+      - name: Install clojure tools
+        uses: DeLaGuardo/setup-clojure@13.4
+        with:
+          bb: latest
       - name: Run ASCIIDoc
         id: adocbuild
         uses: tonynv/asciidoctor-action@master
         with:
-          program: "asciidoctor -D build index.adoc"
+          program: "bb build"
       - name: Print execution time
         run: echo "Time ${{ steps.adocbuild.outputs.time }}"
       - name: Upload artifact

.gitignore

@@ -1,2 +1,3 @@
 build/
 .clj-kondo/
+.cpcache/

bb.edn

@@ -1,2 +1,6 @@
 {:tasks
- {build (shell "asciidoctor -D build -b html5 index.adoc")}}
+ {docstrings
+  {:task (clojure "-M" "build.clj")}
+  build
+  {:depends [docstrings]
+   :task (shell "asciidoctor -D build -b html5 index.adoc")}}}

build.clj

@@ -0,0 +1,23 @@
+(ns build
+  (:require [clojure.java.io :as io]
+            [clojure.string :as str]
+            [integrant.core :as ig]))
+
+(defn- ->asciidoc [s]
+  (-> s
+      (str/replace #"(?m)^  " "")
+      (str/replace #"(\n[^-][^\n]*)\n-" "$1\n\n-")))
+
+(def keywords
+  [:duct.logger/simple
+   :duct.module/logging])
+
+(ig/load-annotations)
+
+(with-open [writer (io/writer "keywords.adoc")]
+  (binding [*out* writer]
+    (doseq [kw (sort keywords)]
+      (println (str "=== " kw))
+      (newline)
+      (println (->asciidoc (:doc (ig/describe kw))))
+      (newline))))

deps.edn

@@ -0,0 +1,4 @@
+{:paths ["."]
+ :deps {org.clojure/clojure {:mvn/version "1.12.2"}
+        integrant/integrant {:mvn/version "1.0.0"}
+        org.duct-framework/module.logging {:mvn/version "0.6.6"}}}

index.adoc

@@ -2022,3 +2022,7 @@ clj꞉user꞉> (go)
 
 To reset the project, you can use `(reset)` at the REPL, or run the
 command: *Calva: Refresh All Namespaces*.
+
+== Keywords
+
+include::keywords.adoc[]

keywords.adoc

@@ -0,0 +1,41 @@
+=== :duct.logger/simple
+
+A simple buffered logger that adheres to the duct.logger/Logger protocol.
+
+Takes the following options:
+
+- `:appenders` - a collection of appender configurations
+- `:buffer-size` - the size of the logging ring buffer (default: 1024)
+- `:polling-rate` - the delay in ms between each poll (default: 5)
+- `:poll-chunk-size` - the max no. of logs to process each poll (default: 8)
+- `:shutdown-delay` - the delay in ms before shutting down (default: 100)
+- `:shutdown-timeout` - the time to wait in ms for shutdown (default: 1000)
+
+Appender configurations are maps that have a `:type` option that can be one
+of:
+
+- `:file` - logs are appended to a file
+- `:stdout` - logs are sent to STDOUT
+
+File appenders have the following options:
+
+- `:levels` - a set of log levels (or `:all`) to limit the appender to
+- `:brief?` - whether to omit timestamps and levels (defaults to false)
+
+STDOUT appenders have the following options:
+
+- `:levels` - a set of log levels (or `:all`) to limit the appender to
+- `:path` - the path of the log file
+
+=== :duct.module/logging
+
+A Duct module that adds logging to the configuration using the
+`:duct.logger/simple` component. Takes no options, but uses a different
+logging setup depending on the active profile:
+
+- `:main` - write all logs in full to STDOUT
+- `:repl` - write all logs to `logs/repl.log` and `:report` level logs to
+            STDOUT in brief (no timestamp)
+
+- `:test` - write all logs to `logs/test.log`
+