Discussion:
ANN: Full, continuously updated documentation for clojure.contrib
(too old to reply)
Tom Faulhaber
2009-05-04 06:41:40 UTC
Permalink
Hello everybody,

As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.

It is now up and running and you can use the results here:

http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib

It includes:
* An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
* An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(at http://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json -
still very much under development).

Each page has a sidebar to allow for quick access from place to place.

All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.

The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).

To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.

Happy perusing!

Tom
Christopher Taylor
2009-05-04 06:45:33 UTC
Permalink
Tom,

thanks, that's great! I think it would be really useful if the
overview appeared as a link on the contrib landing page.

all the best,
--Chris
Post by Tom Faulhaber
Hello everybody,
As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.
http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib
* An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
* An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(at http://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json -
still very much under development).
Each page has a sidebar to allow for quick access from place to place.
All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.
The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).
To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.
Happy perusing!
Tom
Mark Volkmann
2009-05-04 11:06:21 UTC
Permalink
This is great! I hope the contrib authors will take the time to
improve their documentation where needed and add some examples for
functions and macros whose use isn't obvious.
Post by Tom Faulhaber
Hello everybody,
As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.
http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib
 * An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
 * An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(at http://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json -
still very much under development).
Each page has a sidebar to allow for quick access from place to place.
All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.
The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).
To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.
Happy perusing!
Tom
--
R. Mark Volkmann
Object Computing, Inc.
e
2009-05-04 11:06:49 UTC
Permalink
is it encouraged for people to post questions to that wiki? and do they end
up near what the question is referring to?

For example, I was just looking at the docs there for "cond/cond-let" and
thought a discussion could help make the docs more immediately penetrable.
Post by Tom Faulhaber
Hello everybody,
As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.
http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib
* An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
* An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(at http://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json -
still very much under development).
Each page has a sidebar to allow for quick access from place to place.
All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.
The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).
To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.
Happy perusing!
Tom
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Clojure" group.
To post to this group, send email to ***@googlegroups.com
To unsubscribe from this group, send email to clojure+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/clojure?hl=en
-~----------~----~----~----~------~----~------~--~---
Antony Blakey
2009-05-04 11:32:00 UTC
Permalink
This is really good.

Have you considered a mechanism for including richer documentation per
contribution/namespace, ala javadocs package document e.g. html files
with images etc ?
Post by Tom Faulhaber
Hello everybody,
As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.
http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib
* An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
* An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(at http://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json -
still very much under development).
Each page has a sidebar to allow for quick access from place to place.
All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.
The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).
To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.
Happy perusing!
Tom
Antony Blakey
-------------
CTO, Linkuistics Pty Ltd
Ph: 0438 840 787

In anything at all, perfection is finally attained not when there is
no longer anything to add, but when there is no longer anything to
take away.
-- Antoine de Saint-Exupery
Andrew Wagner
2009-05-04 11:33:01 UTC
Permalink
Absolutely brilliant. Exactly what clojure-contrib and the clojure community
needed. Thank you!
Post by Tom Faulhaber
Hello everybody,
As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.
http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib
* An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
* An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(at http://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json -
still very much under development).
Each page has a sidebar to allow for quick access from place to place.
All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.
The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).
To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.
Happy perusing!
Tom
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Clojure" group.
To post to this group, send email to ***@googlegroups.com
To unsubscribe from this group, send email to clojure+***@googlegroups.com
For more options, visit this group at http://groups.google.com/group/clojure?hl=en
-~----------~----~----~----~------~----~------~--~---
Tom Faulhaber
2009-05-04 16:23:49 UTC
Permalink
Glad to hear everyone likes it.

Here's my responses to the various comments here:

Chris: Rich added a link on the landing page while I was writing this
note. Thanks, Rich!

Mark: I hoping that the visibility of this page will spur the
contributors (myself included!) to ever higher levels of
documentation. Don't hide your light under a bushel, guys!

e: Hmm, I think comments should work fine even though I'm regenerating
the pages (I haven't tested it). However the google group might be a
better place for questions because people watch it pretty closely. I
would think that the wiki pages would be better for various
elucidations of subtleties of the interface. YMMV, of course.

Antony: There is a way for authors to add links either to other pages
in the wiki or externally. See DataLog and Monad for examples of how
this works. One of the issues here is that doc strings are repurposed
in a lot of ways and authors generally only want to write docs once so
we need to keep the formatting very simple and not assume that folks
will be reading the docs on the wiki.

Tom
Antony Blakey
2009-05-05 11:20:25 UTC
Permalink
Post by Tom Faulhaber
Antony: There is a way for authors to add links either to other pages
in the wiki or externally. See DataLog and Monad for examples of how
this works. One of the issues here is that doc strings are repurposed
in a lot of ways and authors generally only want to write docs once so
we need to keep the formatting very simple and not assume that folks
will be reading the docs on the wiki.
The problem with relying on links is that it separates the
documentation from the code - the documentation is less likely to be
written and maintained if it's not right there, with the source files,
and that's ignoring the issues of tool support and version control.

Antony Blakey
-------------
CTO, Linkuistics Pty Ltd
Ph: 0438 840 787

In anything at all, perfection is finally attained not when there is
no longer anything to add, but when there is no longer anything to
take away.
-- Antoine de Saint-Exupery
Tom Faulhaber
2009-05-06 07:25:43 UTC
Permalink
Yeah, no doubt.

However the goal of this project was not to develop a new, more
sophisticated mechanism for documentation, but rather to expose what
was already available.

The discussion you bring up is more of a language discussion (in the
sense of supporting a more 'literate' style over the more
'traditional' style) than anything having to do with contrib in
particular.

Tom
Tom Faulhaber
2009-05-04 16:30:23 UTC
Permalink
By the way, source of the robot is available on GitHub, for those who
appreciate fine masochism:

http://github.com/tomfaulhaber/contrib-autodoc/

Really, nothing to see there, but we like to be open.

Enjoy!
Post by Tom Faulhaber
Hello everybody,
As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.
http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib
 * An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
 * An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(athttp://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json-
still very much under development).
Each page has a sidebar to allow for quick access from place to place.
All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.
The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).
To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.
Happy perusing!
Tom
kkw
2009-05-04 23:53:59 UTC
Permalink
Tom,

This is a really helpful service. Thank you very much! It's
already helped me find stuff in the clojure.contrib.sql package that I
didn't have the smarts to originally search.

Kev
Post by Tom Faulhaber
By the way, source of the robot is available on GitHub, for those who
http://github.com/tomfaulhaber/contrib-autodoc/
Really, nothing to see there, but we like to be open.
Enjoy!
Post by Tom Faulhaber
Hello everybody,
As many of you know, I have been working on a "contrib autodoc robot"
for the last little while.
http://code.google.com/p/clojure-contrib/wiki/OverviewOfContrib
* An overview of each namespace in contrib (including the author and
shortcut links to documentation for each of the functions).
* An API page for each name space that includes the doc string for
each function or variable in the namespace and a direct link to the
source for that function or variable.
* An index of all the documented functions and variables so that you
can find them by name.
* A JSON file that allows other tools to build off this information
(athttp://clojure-contrib.googlecode.com/svn/wiki/ApiDocIndex.json-
still very much under development).
Each page has a sidebar to allow for quick access from place to place.
All the pages are stored in the wiki on the google code home for
clojure-contrib. This is both a blessing and a curse, since the google
code wiki is a little brain-dead. As a result, the formatting is not
as awesome as I would like.
The goal of this project is to make contrib a more open and accessible
resource for the community. Please take advantage of this to see and
understand the great stuff that folks have added to contrib for your
programming pleasure. I will be making sure it is kept up-to-date
(eventually that will be automated, but for now I have to type "ant"
once in a while).
To contrib authors: I have added metadata to your namespaces. Please
update and correct it as you would like. The updates will be
propagated to the site. Also, please review the doc for your
contributions to make sure it is complete and correct in general. Let
me know if anything doesn't seem to be going through the wringer
correctly.
Happy perusing!
Tom
Stephen C. Gilardi
2009-05-24 00:06:48 UTC
Permalink
Hi Tom,

I like the docs a lot. Thanks for making the robot!

I have a suggestion for a refinement.

We've received an issue for clojure-contrib noting that the doc for
zip-filter at:

http://code.google.com/p/clojure-contrib/wiki/ZipFilterApiDoc

contains:

Usage:

(ns <your-namespace>
(:use clojure.contrib.zip-filter))

This doesn't work as written because clojure.contrib.zip-filer defines
ancestors and descendants which are also defined by clojure.core.

There are at least a couple of ways to fix this:

- change :use (which may not always be correct) to :require (which is
always correct)

- include in the usage example any :refer-clojure clauses that are
present in the contrib's ns form.

I recommend the first option. Please consider making a change along
these lines.

Thanks,

--Steve
Post by Tom Faulhaber
By the way, source of the robot is available on GitHub, for those who
http://github.com/tomfaulhaber/contrib-autodoc/
Really, nothing to see there, but we like to be open.
Enjoy!
Tom Faulhaber
2009-05-25 04:02:36 UTC
Permalink
Good thought, Steve. Option 1 is now done.
Post by Stephen C. Gilardi
Hi Tom,
I like the docs a lot. Thanks for making the robot!
I have a suggestion for a refinement.
We've received an issue for clojure-contrib noting that the doc for  
       http://code.google.com/p/clojure-contrib/wiki/ZipFilterApiDoc
        (ns <your-namespace>
          (:use clojure.contrib.zip-filter))
This doesn't work as written because clojure.contrib.zip-filer defines  
ancestors and descendants which are also defined by clojure.core.
        - change :use (which may not always be correct) to :require (which is  
always correct)
        - include in the usage example any :refer-clojure clauses that are  
present in the contrib's ns form.
I recommend the first option. Please consider making a change along  
these lines.
Thanks,
--Steve
Post by Tom Faulhaber
By the way, source of the robot is available on GitHub, for those who
http://github.com/tomfaulhaber/contrib-autodoc/
Really, nothing to see there, but we like to be open.
Enjoy!
 smime.p7s
3KViewDownload
Max Suica
2009-05-24 18:59:45 UTC
Permalink
Hey, is there such a wiki/doc for core clojure? The wiki for clojure-
contrib's project page is so nice, but clojure's wiki has very little.
Heh, I've been using clj-doc to make my own reference for it, but the
wiki is a lot prettier. It would be nice to generate one for core.
I've looked at the robot code but it was scary and I put it away for
now, so I am still wondering if the generator can be decoupled from
clojure-contrib's and the wiki's svn to make a generic library doc
generator.

On the notion of separating the documentation from the code, shouldn't
it be possible to generate a wiki interface for each code branch, and
allow changes in the wiki to be commited as changes to the doc strings
in the code? It might be fairly comfortable for coders to edit
documentation like that, but then again, it's pretty easy to just open
a file and add to a doc-string.

max
Tom Faulhaber
2009-05-25 04:25:11 UTC
Permalink
Max,

Sorry that the code for the robot is such a stew. The way it should
work is to build all the doc data and then format that data for the
wiki, but that's not how it happened. I'll probably do that when Rich
moves contrib to a different wiki :-).

A lot of the code in there is just to deal with the google code wiki
itself which is a little nasty. Unfortunately, the assumptions about
that are just kind of mixed in all over the place. It has occurred to
me to do an html-only version, but I'm mostly thinking about other
things just at the moment.

That having been said, there's no reason that the same basic idea
couldn't be used to generate anything from the doc-strings and other
metadata. The kernel of this came from some code that Rich Hickey
wrote to create the API reference for clojure.org. He posted it here:
http://paste.lisp.org/display/77339.

Tom
Post by Max Suica
Hey, is there such a wiki/doc for core clojure? The wiki for clojure-
contrib's project page is so nice, but clojure's wiki has very little.
Heh, I've been using clj-doc to make my own reference for it, but the
wiki is a lot prettier. It would be nice to generate one for core.
I've looked at the robot code but it was scary and I put it away for
now, so I am still wondering if the generator can be decoupled from
clojure-contrib's and the wiki's svn to make a generic library doc
generator.
On the notion of separating the documentation from the code, shouldn't
it be possible to generate a wiki interface for each code branch, and
allow changes in the wiki to be commited as changes to the doc strings
in the code? It might be fairly comfortable for coders to edit
documentation like that, but then again, it's pretty easy to just open
a file and add to a doc-string.
max
Continue reading on narkive:
Loading...