Recently, I discovered the "story" literate programming tool for Clojure, which I prefer to marginalia: https://github.com/jedahu/story
I had tried marginalia, but ran into the following problems: 1. Didn't really handle all markdown notations properly, so I had a lot of trouble getting the formatting of the text to look right. 2. The code column wasn't wide enough and long lines of code didn't wrap, so important things were just getting truncated. 3. As far as I could tell, there was no way to control what order the various namespaces appeared in the uberdoc file. 4. Didn't build any sort of index. I had never heard of "story", but ran across a mention of it while looking through the issues on marginalia's github site, so I decided to give it a try. It's similar to marginalia, in that it's not true literate programming -- it doesn't let you freely order your comments and code irrespective of how they appear in the final files, but is a tool for extracting long comments written in markdown in order to weave some sort of narrative explanation of why the code is written the way it is. I was really impressed with "story", and with a couple fairly minor exceptions, it does exactly what I need it to do. Has anybody else used story? Does anybody know whether story is still being maintained? The version on github is written in Clojure 1.2, and I couldn't get the leiningen plugin (https://github.com/jedahu/lein-story) to work with a current version of leiningen. So I just cloned the repository from github and compiled it locally, creating an executable jar to run. Like I said, it pretty much does what I want it to do out of the box, but I have some reservations about writing all my code using a tool that might become harder to use as Clojure and lein continue to evolve, assuming there are no plans to further update the tool. So, any thoughts about story? Also, are there any other actively supported documentation tools for Clojure that I should look at? In addition to marginalia and story, here's what I'm aware of: In the literate programming department: * org-babel (Only works with emacs. Do stacktraces refer back to correct file and line numbers?) * Tim Daly posted a tool that lets him essentially write Clojure inside a TeX document. Seems to require a very different workflow to use effectively. In the API documentation department: * autodoc (doesn't work on Windows last I checked) * clodox (haven't tried, but looks good) Right now, I care more about the literate programming side of things, but I'm always interested in learning anything about good documentation tools and practices for Clojure. Thanks, Mark -- -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
