As someone who had been learning Clojure for almost a year I thought it would be an educational experience for me. Fogus felt the same way and he rest is history.
I didn’t know what I was getting myself into.
But after four years I’m starting to get the hang of this whole open source maintainer thing.
So now that I’m not deathly afraid of someone opening up new issues I encourage you to try it out.
It takes a minute to run it on your code base and at the output to your GitHub pages branch.
This is pretty cool, I like the way this works. So this is sort of like supplemental right? You should have other docs explaining how to use the library too?
I think it depends, but in general if literate programming is practiced “by the book” (the way Knuth intended it) then the code are the docs. Or actually the other way around, the docs are the code.
Literate programs are written as an uninterrupted exposition of logic in an ordinary human language, much like the text of an essay, in which macros are included to hide abstractions and traditional source code.
I don’t know of many modern examples of bigger projects that actually do this, but it seems really great for small focused libraries where it’s actually quite nice to have the author walk you through the implementation like this.
I find it’s good for when the project is new and there is a lot of churn,
it’s easier to keep your docs up to date when they’re close to the code.
At least in theory =)
thi.ng/geom is a very large Clojure project that is written as org-mode files that are then processed to extract the inline Clojure code, with quite impressive results.
Btw I’ve started evaluating marginalia at work today, looks great so far! I was wondering whether there is any support for embedding images or if this may be a planned feature.
It’s been awhile since I’ve tried it, luckily I’m doing some library work right now.
I was worried about the natural structure of clojure programs messing with the narrative (least general to most general as you go down the file) but it’s pretty nice!
I like having a reason to use markdown in docstrings also.
Knuth’s thing was code + comments + design documentation in one place. User documentation would be written separately, though probably using similar tools to inline examples and such.
I’d love to get into literate programming and org mode. Is org (mode/file/workflow) emacs exclusive or could I write & postprocess to ClojureScript with any tooling?
Do you know how the thi.ng repos (all of them are great sources of inspiration/for learning!) are processed/generated? I don’t seem to be able to find something, maybe I missed it.
Org-mode is mostly an emacs things, though there are some non-emacs tools that can work with org files. The thi.ng repos are all org-mode in emacs with some shell scripts to publish the website and push a fresh version to clojars.
Has anybody here used org-mode in combination with another IDE or external tools and been able to synchronize source files with the literate programming pipeline? For me tool integration would be the biggest benefit of marginalia or hydrox, but it is then limited to Clojure source code. On the other hand this is then not ideal to generate something like a PDF or use other languages like Python. org-mode would be way better for a system specification, for example.
I have been using marginalia on one of my projects. What I am missing the most is a way to control the order of the namespaces in the extracted documentation. Without it, I feel it is difficult to create a proper reading-flow. Maybe it is possible?
