Hey Mark, I don't know of any publicly available tools besides autodoc. My understanding is that Zack was keeping the source to clojuredocs closed, at least for now. While I assume his extraction code is in Clojure, the actual clojuredocs presentation code is a Ruby on Rails app [1]
Whether autodoc is the right basis for what you would like depends on exactly what you would like. The issue of running on Windows is a red herring. While it does have bugs on Windows, I don't think they'd be difficult to fix. They seem to mostly be of the form of not using path separators correctly and being disciplined enough about using java.io.File instead of just hacking up file name strings. A motivated user should be able to get it all working pretty quickly, I would think (patches very welcome!). It's on my list to do, but I haven't gotten to it yet. The real issue is whether you want information in comments, in "formatted docstrings" or in non-docstring metadata. Since docstrings are already metadata and I didn't want to mess with their usability in other contexts, I took the last approach. I don't think putting the info in comments (as naturaldocs does) would really be in the Clojure style. Having a tool that detected standard formatting in doc strings seems like the right way to go to me. The trick would be finding a format that wasn't ugly or confusing to people accessing docstrings another way (like from Slime or the REPL). Examples, on the other hand, might go better in a separate metadata field. Hmmm... All of this should be possible to build on top of autodoc fairly easily. Autodoc basically has four parts: - collect-info walks the source tree (by loading each file in turn) and returns a structure describing the public variable it found there, organized by namespace. - build-html generates a directory of html (and optionally a JSON index) based on this data. - The HTML templates, CSS files and images used to create the default format used on clojure.github.com/clojure. These are all replaceable as long as you keep the tags that the build-html code uses (assuming you want that information). - the rest of the goop deals with the nastiness of automating git interactions, creating doc trees that span branches, handling the fact that the program is written in Clojure and also used to document multiple, incompatible versions of Clojure, generate supporting docs written using markdown, etc. Two easy things to do would be: - Recognize additional metadata fields in collect info and use them in build-html (category markers, for instance), or - After collect-info, parse the docstrings themselves and add elements to the generated structures to represent docstring-embedded data. Then use that in build-html. Note that if you want to pull info from comments, autodoc probably isn't the right tool since it's driven completely from the compiled namespaces and metadata. I am happy to see people fork autodoc[2] and twist it to their own vision of what makes great documentation. This is a nice area in which to improve stuff. I'll happily integrate changes that fit the main mission of autodoc. Enjoy, Tom [1] http://groups.google.com/group/clojure/browse_thread/thread/a97d472679f2cade/53eec6db0ca0c82f?lnk=gst&q=clojuredocs+ruby#53eec6db0ca0c82f [2] Here it is: http://github.com/tomfaulhaber/autodoc -- 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
