Some experiments with tools for a reference manual

[jneem]

I tried out both antora and mkdocs. Antora has the disadvantage of being in asciidoc. Which is fine, but most of our existing documentation is in markdown. mkdocs uses markdown, is packaged in nixpkgs, and seems pretty extensible/customizable.

A couple things I've run into so far:

• the markdown flavor used by mkdocs doesn't support codeblocks that start with ```nickel #repl. Their syntax is ``` { .nickel #repl }. I'm not sure yet whether that's compatible with comrak.
• mkdocs does syntax highlighting with highlight.js, or alternatively there's a material theme with support for pygment. Neither of these has nickel support built-in, so we'll need to figure out something...

[github-actions]

Bencher Report

Branch	docs
Testbed	ubuntu-latest

Click to view all benchmark results

Benchmark	Latency	microseconds (µs)
fibonacci 10	📈 view plot 🚷 view threshold	314.24 µs
foldl arrays 50	📈 view plot 🚷 view threshold	402.31 µs
foldl arrays 500	📈 view plot 🚷 view threshold	3,805.70 µs
foldr strings 50	📈 view plot 🚷 view threshold	4,610.80 µs
foldr strings 500	📈 view plot 🚷 view threshold	46,653.00 µs
generate normal 250	📈 view plot 🚷 view threshold	40,822.00 µs
generate normal 50	📈 view plot 🚷 view threshold	1,680.10 µs
generate normal unchecked 1000	📈 view plot 🚷 view threshold	2,188.90 µs
generate normal unchecked 200	📈 view plot 🚷 view threshold	455.41 µs
pidigits 100	📈 view plot 🚷 view threshold	2,494.60 µs
pipe normal 20	📈 view plot 🚷 view threshold	706.78 µs
pipe normal 200	📈 view plot 🚷 view threshold	6,202.40 µs
product 30	📈 view plot 🚷 view threshold	261.13 µs
scalar 10	📈 view plot 🚷 view threshold	610.98 µs
sum 30	📈 view plot 🚷 view threshold	265.07 µs

🐰 View full continuous benchmarking report in Bencher