code.doc
The publish pipeline, the theme layer, and the authoring model.
This page is the compact reference for extending code.doc itself: what the pipeline does, where to plug in richer authoring blocks, and how the code site now uses it.
1 Pipeline
code.doc already had the right backbone for a documentation compiler. The work in this refresh keeps that backbone and upgrades the pieces around it.
Parse
Clojure pages and markdown pages are parsed into a common element structure.
Collect + link
References, API entries, numbering, anchors, and stencil links are resolved into a renderable interim representation.
Render
A theme provides render functions and templates that turn the interim structure into static HTML.
2 Core entry points
deploy-template ^
[] [site] [site params] [site params project] [site params lookup project]deploys the theme for a given site
v 3.0
(invoke/definvoke deploy-template
[:task {:template :code.doc.theme
:params {:title "DEPLOY TEMPLATE ASSETS"}
:main {:fn #'executive/deploy-template}}])link
(deploy-template "hara")
init-template ^
[] [site] [site params] [site params project] [site params lookup project]initialises the theme template for a given site
v 3.0
(invoke/definvoke init-template
[:task {:template :code.doc.theme
:params {:title "INITIALISE TEMPLATE"}
:main {:fn #'executive/init-template}}])link
(init-template "hara")
v 4.1
(defn make-audit-project
([]
(make-audit-project nil))
([_]
(let [project (make-project)]
(assoc project
:code.doc/source-namespaces (manage/source-namespaces project)
:code.doc/coverage (manage/documented-coverage project)))))link
(make-audit-project) => (contains {:code.doc/source-namespaces coll? :code.doc/coverage map?})
v 3.0
(defn make-project
([]
(make-project nil))
([_]
(let [project (project/project)]
(assoc project
:lookup (project/file-lookup project)
:publish (config/load (or (config/resolve (:publish project))
+config+))))))link
(make-project) => map?
missing ^
[] [ns] [ns params] [ns params project] [ns params lookup project]checks for namespaces not yet referenced by code.doc pages
v 4.1
(invoke/definvoke missing
[:task {:template :code.doc.audit
:params {:title "MISSING CODE.DOC NAMESPACES"}
:main {:fn #'manage/missing-namespaces}}])link
(missing)
3 Management + coverage
documented-coverage ^
[{:keys [publish root], :as project}]returns a namespace to pages coverage map
v 4.1
(defn documented-coverage
([{:keys [publish root] :as project}]
(reduce-kv
(fn [coverage site site-config]
(reduce-kv
(fn [coverage page page-config]
(let [page-id (symbol (name site) (name page))
elements (parse/parse-file (:input page-config) {:root root})]
(reduce (fn [coverage ns]
(update coverage ns (fnil conj []) page-id))
coverage
(mapcat element-namespaces elements))))
coverage
(:pages site-config)))
{}
(:sites publish))))link
(with-redefs [parse/parse-file (fn [_ _] [{:type :api :namespace "code.doc"} {:type :reference :refer "code.doc.executive/render"}])] (documented-coverage {:root "." :publish {:sites {:foundation.code {:pages {'index {:input "docs/index.clj"}}}}}})) => {'code.doc ['foundation.code/index] 'code.doc.executive ['foundation.code/index]}
missing-namespaces ^
[ns _ _ #:code.doc{:keys [coverage]}]returns a marker for namespaces that are not referenced by code.doc pages
v 4.1
(defn missing-namespaces
([ns _ _ {:code.doc/keys [coverage]}]
(if-not (contains? coverage ns)
[:missing-code-doc])))link
(missing-namespaces 'code.doc {} nil {:code.doc/coverage {}}) => [:missing-code-doc] (missing-namespaces 'code.doc {} nil {:code.doc/coverage {'code.doc ['foundation.code/index]}}) => nil
4 Walkthrough
4.1 Preparing the project
make-project assembles the environment needed by the publish pipeline: the project map, namespace lookup, and publish config. all-pages then builds a lookup of every documented page.
create the publish environment
(doc/make-project)
=> map?list all documentation pages
(-> (doc/make-project)
(executive/all-pages)
keys)
=> seq?4.2 Rendering a page
publish renders a page key to HTML. With :write false it previews the output and reports whether anything changed.
render a single page without writing
(doc/publish '[code/code-test] {:write false})
=> (contains {:path string?
:updated boolean?})4.3 Coverage audit
missing reports source namespaces that are not referenced by any documentation page. Use it to find gaps in the docs.
run a coverage audit
(doc/missing '[code.doc]
{:print {:result false :summary false}
:return :all})
=> any4.4 End-to-end: render a single page
Combine make-project and publish to render a single page without writing. The result shows the output path and whether the HTML changed.
render one documentation page
(doc/publish '[code/code-test] {:write false})
=> (contains {:path string?
:updated boolean?})5 Source references
(invoke/definvoke publish
[:task {:template :publish
:params {:title "PUBLISHING HTML FILES"
:parallel true}
:main {:fn #'executive/render}}])(invoke/definvoke missing
[:task {:template :code.doc.audit
:params {:title "MISSING CODE.DOC NAMESPACES"}
:main {:fn #'manage/missing-namespaces}}])(defn documented-coverage
([{:keys [publish root] :as project}]
(reduce-kv
(fn [coverage site site-config]
(reduce-kv
(fn [coverage page page-config]
(let [page-id (symbol (name site) (name page))
elements (parse/parse-file (:input page-config) {:root root})]
(reduce (fn [coverage ns]
(update coverage ns (fnil conj []) page-id))
coverage
(mapcat element-namespaces elements))))
coverage
(:pages site-config)))
{}
(:sites publish))))