On Apr 13, 11:14 pm, Tom Faulhaber <tomfaulha...@gmail.com> wrote:
> [This is specifically for contrib authors, but also for anyone whose
> interested.]
>
> There was some discussion (or maybe the wailing and gnashing of teeth)
> about the fact that there's lots of cool functionally coming into
> clojure.contrib but no easily accessible documentation. I had been
> thinking about this already and figured maybe I'd set up the framework
> for fixing it.
>
> My idea is to use the namespace and var metadata to auto-generate a
> set of documentation that has:
> - an overview page that lists the namespaces in contrib and presents a
> summary of each derived from the namespace metadata.
> - each entry on the namespace overview page will have a link to an API
> page for that namespace. That page will be basically like the API page
> on clojure.org.
> - probably should have an index page as well, but I haven't thought
> about it much.
> - an ability to link from a namespace to a custom created piece of
> documentation (like the nice DatalogOverview that Jeffery wrote).
>
> I've written the code that builds (a first cut of) this stuff from the
> namespaces. It uses the following metadata:
>
> On the namespace:
> - :author to supply a string with the author(s) name(s)
> - :wiki-doc to supply a wiki specific doc string (that can include
> wiki markup) or, if that doesn't exist, we fall back to
> - :doc the default doc string
>
> On the vars, I use:
> :wiki-doc and :doc, as above
> :macro - to indicate if it's a macro
> :arglists to grab the arglist
>
> The last two are set automatically by defn and defmacro.
>
> AUTHORS PLEASE NOTE: In order for this to be useful these fields need
> to be filled in for your contributions. The system will work without
> it, just not as nicely.
>
> The next stage of my plan is to build a robot that watches the
> subversion repository and updates the doc on every checkin. Therefore
> the doc will typically correspond to the tip of the tree.
>
> To avoid thinking too hard, I'm planning to use the wiki on
> clojure.contrib's googlecode page because (a) there's almost nothing
> on it now and (b) it's easy to use subversion to update stuff there.
> Whether this is the right place long-term is another question that we
> can worry about once it's running.
>
> Does all of this seem like the right direction? Comments? Suggestions?
>
The wiki on clojure.contrib's googlecode page is definitely the right
place for the contrib docs, contrib members should please feel free to
use it. That's one of the reasons I moved to googlecode.
Thanks,
Rich
--~--~---------~--~----~------------~-------~--~----~
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
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
-~----------~----~----~----~------~----~------~--~---
