Clojure is a truly amazing language and still a very young one. There is already a substantial quantity of documentation available for Clojure and some of its libraries. Yet, when talking about documentation, some is not enough. Sure, there's the REPL with all its bells and whistles, but sometimes I prefer to navigate through a well formatted API document using a browser. There's already some solutions for this, one on which I worked for the defunct Compojure website (which was based on similar code for Clojure) and another more serious attempt in clojure-contrib, gen-html-docs by Craig Andera. This library only output HTML and there arise a small (but annoying) problem: not all projects have their documentation formatted in HTML. For example, the new Compojure website runs on DokuWiki which have its own syntax and Gitorious integrated Wiki, used for ClojureQL, is using Markdown. If only every Wiki engine would understand Creole!
clj-doc
To be able to solve the above problem, I decided to start a new project called clj-doc. For now it's pretty much just a weekend coding session, but I'll continue to work on it so that one day it will be the best tool available to generate documentation for Clojure code. The basic usage is done through the gen-doc macro.
user> (use 'clj-doc) nil user> (gen-doc clj-doc.utils) ("<!DOCTYPE html ...Documentation for clj-doc.utils...")
This gives us a sequence of strings being the rendered output of each namespaces given using the default markup language. Namespaces could also be grouped using nested sequences, for now clj-doc support only one level of nesting. Another notable feature is that namespace groups can be specified using regular expressions. Here's an example demonstrating all these methods at once.
user> (use 'clojure.contrib.pprint) nil user> (pprint (gen-doc clj-doc (clj-doc.markups clj-doc.generator clj-doc.utils) #"clj-doc\.markups\.")) ("<!DOCTYPE html ...Documentation for clj-doc..." "<!DOCTYPE html ...Documentation for clj-doc.markups, clj-doc.generator, clj-doc.utils..." "<!DOCTYPE html ...Documentation for clj-doc.markups.creole, clj-doc.markups.dokuwiki, ...")
Writing to Files
Usually you would want to write the documentation for your library to a file. I've added basic support for this with the gen-doc-to-file macro. It behaves exactly as gen-doc but writes each of the resulting documentation strings to a file.
user> (gen-doc-to-file "~/test.html" clj-doc) nil
If you use more than one group of namespaces, this macro will write them into multiple files that will be numbered starting with zero by appending a number before the last dot if there's one, at the end otherwise. I intend to make this argument a format string where you can specify more complex filenames in a next version. So, if you got any ideas about how to design or implement such feature, I encourage you to add a comment to this post.
Supported Markups
Up until now, we've only been using the default output markup. The main point of this library being generating something else than HTML, we better have a way to use another markup language. Before talking about how to do that, lets look under the hood.
(ns clj-doc.markups.creole "Creole markup." (use clj-doc.markups)) (defmarkup #^{:doc "Creole markup."} creole :title #(str "\n= " % " =") :namespace #(str "\n== " % " ==") :section #(str "\n=== " %1 " ===\n" %2) :var-name #(str "\n==== " % " ====") :var-arglist #(str "\n**" % "**\\\\") :var-doc #(str "\n\n" %))
This is the current implementation for the Creole Wiki markup generator. All markups are defined in the same way, they're basically only struct maps, for more details see the clj-doc.markups namespace. The library currently provides four output methods. We've already seen two of them, here's the complete list:
- creole
- dokuwiki
- html-simple
- markdown
To define your own markups, you can take one of the implementations, modify it and see how it work out, the keywords should be explicit enough. The library only look for markups into namespaces starting with "clj-doc.markups." though, but that's just a temporary limitation, eventually you'll be able to pass a markup struct map as an option.
The Option Map
The option map is an optional argument that must be specified before any namespaces. It presently only support two keywords, :markup and :separated-by. The first letting you choose the output method and the second used to change the default page separation behavior.
user> (gen-doc {:markup creole} clj-doc.markups.creole) ("\n= Documentation for clj-doc.markups.creole =\n== clj-doc.markups.creole namespace ==\n=== others ===\n\n==== creole ====\n\nCreole markup.")
The :separated-by option can only take one value, namespace, which makes the macros separate pages between namespaces instead of groups of them.
user> (pprint (gen-doc {:markup markdown :separated-by namespace} #"clj-doc\.markups\.")) ("\n#Documentation for clj-doc.markups.creole..." "\n#Documentation for clj-doc.markups.dokuwiki..." "\n#Documentation for clj-doc.markups.html-simple..." "\n#Documentation for clj-doc.markups.markdown...") nil
The Future
This is a very early release done the worse is better way, so it's still a pretty bare-bone tool. I'll be taking a pause this week to work on more (hopefully) profitable projects, so in the meantime I'll be pleased to ear about any suggestions to improve the way clj-doc works.
Links
- GitHub Project Page
- Example output for ClojureQL (using Markdown)
- Example output for Compojure (using DokuWiki syntax)
No comments:
Post a Comment