A tool for gluing snippets of your Clojure code into your docs. Inspired by literate programming.
Based on rewrite-clj
.
Code is hardly ever optimized for pedagogy. Unlike org-babel, WEB, or noweb, most literate-programming-inspired tools I know of are lacking in one crucial aspect: the sheer difficulty of "out-of-order" presentation of ideas (from the perspective of the resultant code). So, I wanted to experiment and try out something that:
- would provide the bare minimum for creating out-of-order documentation using fragments of actual code
- wouldn't cause noticeable changes in workflow
Supposing you had the following code on your classpath:
(defn my-fn
"An example fn for demonstrative purposes"
[]
(println "hello world!")
(+ 1 1))
and you wanted to include that snippet as-is in your documentation, so that the println
form gets replaced with <<println>>
.
First, add some metadata:
^{:liima/ref :my.ns/my-fn}
(defn my-fn
"An example fn for demonstrative purposes"
[]
^{:liima/ref :my.ns/print}
(println "hello world!")
(+ 1 1))
Next, add the following in a Markdown file:
Here's a neat function:
```
@{{content :my.ns/my-fn :my.ns/print "<<println>>"}}
```
where `<<println>>` is: `@{{content :my.ns/print}}`
Then, evaluate:
(liima.docs/process-notes! {:docs-root "/path/to/docs" :output-root "./target/docs"})
A version of the original Markdown file has been dumped under ./target/docs
with the template replaced:
Here's a neat function:
```
(defn my-fn
"An example fn for demonstrative purposes"
[]
<<println>>
(+ 1 1))
```
where `<<println>>` is: `(println "hello world!")`
For content replacements, currently only content
and ns
(for attempted inference of the code block's namespace) are supported.
Links can be replaced by appending the typical Markdown notation with @
, like so:
@[My Link](./linked-page.md)
which would become
[My Link](./linked-page/index.html)
- All
:liima/ref
values must be either unqualified, or fully qualified, keywords (i.e., can't use::keyword
sugar). - Only code that supports metadata can be tagged