The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Images in autodoc?
 There are currently too many topics in this group that display first. To make this topic appear first, remove this option from another topic. There was an error processing your request. Please try again. Standard view   View as tree
 24 messages

From:
To:
Cc:
Followup To:
Subject:
 Validation: For verification purposes please type the characters you see in the picture below or the numbers you hear by clicking the accessibility icon.

More options Oct 25 2010, 10:05 pm
From: Chris <christopher.ma...@gmail.com>
Date: Mon, 25 Oct 2010 19:05:17 -0700 (PDT)
Local: Mon, Oct 25 2010 10:05 pm
Subject: Images in autodoc?
can?  I'm interested in adding explanatory diagrams to function
documentation as opposed to adding things like logos to the HTML
pages.

Thanks,
Chris

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 3:50 am
From: Tom Faulhaber <tomfaulha...@gmail.com>
Date: Tue, 26 Oct 2010 00:50:54 -0700 (PDT)
Local: Tues, Oct 26 2010 3:50 am
Subject: Re: Images in autodoc?

I haven't really figured out a way to do it that fits in with other
uses of doc strings.

I do know that I want the images to be able to be embedded in the doc
string so that programs like incanter can use the image as part of the
narrative, but I want the "markup" that does it to feel natural to
readers who aren't seeing the image.

Tom

On Oct 25, 7:05 pm, Chris <christopher.ma...@gmail.com> wrote:

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 6:03 am
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Tue, 26 Oct 2010 06:03:25 -0400
Local: Tues, Oct 26 2010 6:03 am
Subject: Re: Images in autodoc?

On Tue, Oct 26, 2010 at 3:50 AM, Tom Faulhaber <tomfaulha...@gmail.com> wrote:

> I haven't really figured out a way to do it that fits in with other
> uses of doc strings.

> I do know that I want the images to be able to be embedded in the doc
> string so that programs like incanter can use the image as part of the
> narrative, but I want the "markup" that does it to feel natural to
> readers who aren't seeing the image.

I'm not sure what sort of markup you've already thought of, but using
something similar to markdown which has the ability to embed resources
within, but specify them later seems to make sense for this purpose:

(defn foo
"this function computes foo, given bar, and returns a handle to a
java.awt.image.BufferedImage, which shows a 3D graph (![example
graph][1]) of the function.

[1]: http://foo.bar/examples/foo-bar.png"
[bar]
...)

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 6:05 am
From: Chris <christopher.ma...@gmail.com>
Date: Tue, 26 Oct 2010 03:05:14 -0700 (PDT)
Local: Tues, Oct 26 2010 6:05 am
Subject: Re: Images in autodoc?
On Oct 26, 3:50 am, Tom Faulhaber <tomfaulha...@gmail.com> wrote:

> I do know that I want the images to be able to be embedded in the doc
> string so that programs like incanter can use the image as part of the
> narrative, but I want the "markup" that does it to feel natural to
> readers who aren't seeing the image.

Maybe something like Markdown link references? E.g.,

(defn foo [x y]
"Blah blah blah, blah blah blah.  Blah blah,
as seen here:

[Figure 1][]

Also remember blah blah blah, and blah blah
as well. Blah blah blah blah blah blah blah
blah blah blah blah blah blah blah.

[Figure 1]: /doc-files/figure-1.png"

(+ x y))

Basically, have all the image file addresses as footnotes.  If you're
reading the docs in the REPL, for instance, you don't have big URL-ish
strings distracting you from the documentation, but all the info is
still there to be parsed out by autodoc.

Chris

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 9:27 am
From: Chris <christopher.ma...@gmail.com>
Date: Tue, 26 Oct 2010 06:27:04 -0700 (PDT)
Local: Tues, Oct 26 2010 9:27 am
Subject: Re: Images in autodoc?
Come to think of it, it might be cool to write doc strings in a kind
of "Clojure-flavored Markdown"... that'd give us images, links, lists,
formatting, etc.  It's also got the benefit of being a familiar
format, and easy to read in unprocessed form.

Chris

On Oct 26, 6:05 am, Chris <christopher.ma...@gmail.com> wrote:

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 9:54 am
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Tue, 26 Oct 2010 09:54:33 -0400
Local: Tues, Oct 26 2010 9:54 am
Subject: Re: Images in autodoc?

On Tue, Oct 26, 2010 at 9:27 AM, Chris <christopher.ma...@gmail.com> wrote:
> Come to think of it, it might be cool to write doc strings in a kind
> of "Clojure-flavored Markdown"... that'd give us images, links, lists,
> formatting, etc.  It's also got the benefit of being a familiar
> format, and easy to read in unprocessed form.

I like that idea, especially if it could be extended to reference other code:

(defn foo
"Creates an echo server using
[create-server][ref:clojure.contrib.server-socket/create-server].
Returns the result of the create-server call which can be shutdown by
using [close-server][ref:clojure.contrib.server-socket/close-server]."
[bar]
...)

I think it'd be easy enough, the markdown compiler would just know
that certain prefixes to references are treated differently.

--
http://www.apgwoz.com

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 10:30 am
From: Chris <christopher.ma...@gmail.com>
Date: Tue, 26 Oct 2010 07:30:54 -0700 (PDT)
Local: Tues, Oct 26 2010 10:30 am
Subject: Re: Images in autodoc?
On Oct 26, 9:54 am, Andrew Gwozdziewycz <apg...@gmail.com> wrote:

> I like that idea, especially if it could be extended to reference other code:

Agreed.  So now that's links to images, web pages, Clojure vars...
anything else?

Chris

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 12:17 pm
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Tue, 26 Oct 2010 12:17:05 -0400
Local: Tues, Oct 26 2010 12:17 pm
Subject: Re: Images in autodoc?

On Tue, Oct 26, 2010 at 10:30 AM, Chris <christopher.ma...@gmail.com> wrote:
> On Oct 26, 9:54 am, Andrew Gwozdziewycz <apg...@gmail.com> wrote:
>> I like that idea, especially if it could be extended to reference other code:

> Agreed.  So now that's links to images, web pages, Clojure vars...
> anything else?

Well, if the markdown generator was written correctly (is there a
markdown.clj? or is this going to be a fresh write? and who's doing
it?) it'd support a way to dispatch the generation based on the prefix
passed to the reference, so supporting other things deemed necessary
wouldn't be so bit a deal.

> Chris

> --
> 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
> For more options, visit this group at

--
http://www.apgwoz.com

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 12:21 pm
From: "Eric Schulte" <schulte.e...@gmail.com>
Date: Tue, 26 Oct 2010 10:21:28 -0600
Local: Tues, Oct 26 2010 12:21 pm
Subject: Re: Images in autodoc?

Chris <christopher.ma...@gmail.com> writes:
> On Oct 26, 9:54 am, Andrew Gwozdziewycz <apg...@gmail.com> wrote:
>> I like that idea, especially if it could be extended to reference other code:

> Agreed.  So now that's links to images, web pages, Clojure vars...
> anything else?

LaTeX equations.  Which are increasingly easy to render in HTML
(e.g. http://www.mathjax.org/).

-- Eric

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 12:25 pm
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Tue, 26 Oct 2010 12:25:30 -0400
Local: Tues, Oct 26 2010 12:25 pm
Subject: Re: Images in autodoc?

On Tue, Oct 26, 2010 at 12:21 PM, Eric Schulte <schulte.e...@gmail.com> wrote:
> Chris <christopher.ma...@gmail.com> writes:

>> On Oct 26, 9:54 am, Andrew Gwozdziewycz <apg...@gmail.com> wrote:
>>> I like that idea, especially if it could be extended to reference other code:

>> Agreed.  So now that's links to images, web pages, Clojure vars...
>> anything else?

> LaTeX equations.  Which are increasingly easy to render in HTML
> (e.g. http://www.mathjax.org/).

I guess the problem is actually making a patch to autodoc to do this all :)

> --
> 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
> For more options, visit this group at

--
http://www.apgwoz.com

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 1:08 pm
From: Tom Faulhaber <tomfaulha...@gmail.com>
Date: Tue, 26 Oct 2010 10:08:19 -0700 (PDT)
Local: Tues, Oct 26 2010 1:08 pm
Subject: Re: Images in autodoc?
Nah, changing the autodoc generation is easy (though we need to figure
out where images go on the input and output sides and move them
around, but that shouldn't be too much of a problem).

The bigger problem is figuring out what to tell folks who type (doc
foo) at the REPL and get a bunch of gobbledegook back. That's the
thing that's been making me look for a better format than markdown.
(Autodoc already does markdown translation for supporting
documentation).

Tom

On Oct 26, 9:25 am, Andrew Gwozdziewycz <apg...@gmail.com> wrote:

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 2:06 pm
From: Chris Maier <christopher.ma...@gmail.com>
Date: Tue, 26 Oct 2010 14:06:34 -0400
Local: Tues, Oct 26 2010 2:06 pm
Subject: Re: Images in autodoc?

On Tue, Oct 26, 2010 at 1:08 PM, Tom Faulhaber <tomfaulha...@gmail.com> wrote:
> The bigger problem is figuring out what to tell folks who type (doc
> foo) at the REPL and get a bunch of gobbledegook back. That's the
> thing that's been making me look for a better format than markdown.
> (Autodoc already does markdown translation for supporting
> documentation).

Is it really that bad reading unformatted markdown, though?  I find it
stashed at the bottom as footnotes.  LaTeX equations, on the other
hand, could get quite hairy (unless they can be footnoted, too)

Are we talking about making changes to the doc macro itself to somehow
either filter or otherwise prettify this markup for REPL consumption?

Tom, what kind of other formats have you been experimenting with?

Chris

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 2:15 pm
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Tue, 26 Oct 2010 14:15:21 -0400
Local: Tues, Oct 26 2010 2:15 pm
Subject: Re: Images in autodoc?
On Tue, Oct 26, 2010 at 2:06 PM, Chris Maier

<christopher.ma...@gmail.com> wrote:
> On Tue, Oct 26, 2010 at 1:08 PM, Tom Faulhaber <tomfaulha...@gmail.com> wrote:
>> The bigger problem is figuring out what to tell folks who type (doc
>> foo) at the REPL and get a bunch of gobbledegook back. That's the
>> thing that's been making me look for a better format than markdown.
>> (Autodoc already does markdown translation for supporting
>> documentation).

> Is it really that bad reading unformatted markdown, though?  I find it
> stashed at the bottom as footnotes.  LaTeX equations, on the other
> hand, could get quite hairy (unless they can be footnoted, too)

I agree. There seems to be a subset of things that people would
actually even use:

(lists-- maybe numbered and bulleted)
* inline code
* *bold*
* _underline_

Areas likely to include gobbledegook:
1. images
3. equations

I'd agree that markdown images and links can get a bit challenging to
read if dense, but maybe an autodoc specific markup language that
addresses the noise and keeps to (sane) conventions is a worthy
approach.

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 4:44 pm
From: Timo Mihaljov <noid....@gmail.com>
Date: Tue, 26 Oct 2010 23:44:33 +0300
Local: Tues, Oct 26 2010 4:44 pm
Subject: Re: Images in autodoc?

On Tue, Oct 26, 2010 at 02:15:21PM -0400, Andrew Gwozdziewycz wrote:
> Areas likely to include gobbledegook:
> [...]
> 2. links (internal. for external links, just use fully qualified URI)

Internal links could be easily handled by trying to resolve all code
blocks with ns-resolve in the namespace containing the docstring. If
the block resolves to a var, make it a link. No gobbledegook needed.
(In practice you'd need a slightly more complicated algorithm to
handle cases where e.g. a parameter shadows an existing var.)

If you wanted to get real fancy, you could even check if the code
block is a list, and then resolve each symbol inside the list, so
that, for example, resolve's docstring would look like this at the
REPL:

user=> (doc resolve)
-------------------------
clojure.core/resolve
([sym])
same as (ns-resolve *ns* sym)

But in the HTML documentation ns-resolve and *ns* would be

--
Timo

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 5:09 pm
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Tue, 26 Oct 2010 17:09:37 -0400
Local: Tues, Oct 26 2010 5:09 pm
Subject: Re: Images in autodoc?

I like that idea. And it does make sense to do that rather than create
some special syntax for those cases. So, that leaves images, and
equations, and any other "rich" types we haven't thought of.

Tom, does this all seem reasonable? If so, how can I help?

Andrew

> --
> Timo

> --
> 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
> For more options, visit this group at

--
http://www.apgwoz.com

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 26 2010, 6:21 pm
From: Chris Maier <christopher.ma...@gmail.com>
Date: Tue, 26 Oct 2010 18:21:39 -0400
Local: Tues, Oct 26 2010 6:21 pm
Subject: Re: Images in autodoc?

> On Tue, Oct 26, 2010 at 4:44 PM, Timo Mihaljov <noid....@gmail.com> wrote:
>> If you wanted to get real fancy, you could even check if the code
>> block is a list, and then resolve each symbol inside the list, so
>> that, for example, resolve's docstring would look like this at the
>> REPL:

>> user=> (doc resolve)
>> -------------------------
>> clojure.core/resolve
>> ([sym])
>>  same as (ns-resolve *ns* sym)

>> But in the HTML documentation ns-resolve and *ns* would be

That is slick.

If there's any way I can help out, too, sign me up.

Chris

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 27 2010, 8:51 am
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Wed, 27 Oct 2010 08:51:06 -0400
Local: Wed, Oct 27 2010 8:51 am
Subject: Re: Images in autodoc?
So, I started working on docup[1], which currently is just for fun,
but my intentions are to find some subset of rules for what we've
discussed in this thread that would be appropriate for autodoc's
markup. It doesn't currently support much at all, but to eliminate
gobbledegook, there's no nesting of simple element types (bold,
italic, underline, inline code). The plan is to support images, lists,
links (by recognizing some common raw URLs), blocks, and eventually
equations (though I'm not convinced they can be simplified for REPL
documentation). For images/figures, the current plan is to use the
footnote approach as discussed previously, but, rearrange the syntax
to eliminate the excess noise:

![caption][ref label] => [ref label: caption]

There would be no supported way to inline the reference for the
image--again, the goal as Tom reiterated originally is to eliminate
excess junk.

On Tue, Oct 26, 2010 at 6:21 PM, Chris Maier

--
http://www.apgwoz.com

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 27 2010, 1:09 pm
From: Ryan Waters <ryan.or...@gmail.com>
Date: Wed, 27 Oct 2010 12:09:55 -0500
Local: Wed, Oct 27 2010 1:09 pm
Subject: Re: Images in autodoc?
What if documentation came in two (embedded?) forms, e.g.

(doc ...)
(doc-verbose ...)

One could be a terse version of the documentation using docstrings
(doc) and the other could have the bells, whistles, etc. to be shipped
with the code in an as yet undetermined manner (as posited by this
post  ; )

- Ryan

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 27 2010, 1:33 pm
From: Christopher Petrilli <petri...@amber.org>
Date: Wed, 27 Oct 2010 13:33:39 -0400
Local: Wed, Oct 27 2010 1:33 pm
Subject: Re: Images in autodoc?
Interestingly, the Python community does something like this.  Usually
there's a very brief explanation of the function/class, a blank line,
then more, and many tools take this into account.  Seems like it might
be a good way to split it up.

Chris

--
| Chris Petrilli
| petri...@amber.org

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 27 2010, 1:41 pm
From: "Eric Schulte" <schulte.e...@gmail.com>
Date: Wed, 27 Oct 2010 11:41:00 -0600
Subject: Re: Images in autodoc?

Christopher Petrilli <petri...@amber.org> writes:
> Interestingly, the Python community does something like this.  Usually
> there's a very brief explanation of the function/class, a blank line,
> then more, and many tools take this into account.  Seems like it might
> be a good way to split it up.

Similarly, in Emacs (elisp) documentation the first line (i.e. ending on
the first newline) is meant to be a single self-contained sentence
describing the function.  Many tools/functions use only this first line.

Another elisp convention that may be worth adopting is the use of
quotes, specifically `' to delimit variable and function names in
documentation.  These then look nice in plain text documentation, but
also allow the documentation engine to turn them into links in those
to add links to documentation without having to worry that every time
you use the word "and" in a sentence it will link to the and macro.

Best -- Eric

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 28 2010, 12:19 pm
From: Tom Faulhaber <tomfaulha...@gmail.com>
Date: Thu, 28 Oct 2010 09:19:30 -0700 (PDT)
Local: Thurs, Oct 28 2010 12:19 pm
Subject: Re: Images in autodoc?
In order to better inform my thinking here, I want to ask: "So what's
the target here?"

Are we looking to enhance Clojure's core documentation or do you have
specific projects of your own for which you'd like these features?

For example, my rationale for images is that I want to be able to
include representative output graphs in the Incanter documentation.

The reason I ask this is that I'm trying to distinguish between things
we're proposing because we'd like to use them ourselves in areas we
control and things we're proposing because we'd like to change the
overall way documentation is done (both reasonable discussions, but
different).

One of the things I'm working on is making available a full dataset
with all the Var doc in clojure format so you can pull sample doc
strings (and other info if you want). This is important for testing
autodoc extensions against the existing population of strings.

Tom

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 28 2010, 1:09 pm
From: Andrew Gwozdziewycz <apg...@gmail.com>
Date: Thu, 28 Oct 2010 13:09:16 -0400
Local: Thurs, Oct 28 2010 1:09 pm
Subject: Re: Images in autodoc?

On Thu, Oct 28, 2010 at 12:19 PM, Tom Faulhaber <tomfaulha...@gmail.com> wrote:
> In order to better inform my thinking here, I want to ask: "So what's
> the target here?"

> Are we looking to enhance Clojure's core documentation or do you have
> specific projects of your own for which you'd like these features?

All of the above, but before core documentation is changed, there
should be proven value, which would come from other projects making
use of the documentation extensions.

> For example, my rationale for images is that I want to be able to
> include representative output graphs in the Incanter documentation.

> The reason I ask this is that I'm trying to distinguish between things
> we're proposing because we'd like to use them ourselves in areas we
> control and things we're proposing because we'd like to change the
> overall way documentation is done (both reasonable discussions, but
> different).

I'm in this for the overall betterment of documentation in the clojure
eco-system on the whole, if people find value in it (which I imagine
people would be ok with richer, non-gobbledegooked documentation, if
that can actually even be done).

> One of the things I'm working on is making available a full dataset
> with all the Var doc in clojure format so you can pull sample doc
> strings (and other info if you want). This is important for testing
> autodoc extensions against the existing population of strings.

Great! This will certainly be helpful in the future.

> --
> 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
> For more options, visit this group at

--
http://www.apgwoz.com

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 28 2010, 2:08 pm
From: Chris Maier <christopher.ma...@gmail.com>
Date: Thu, 28 Oct 2010 14:08:38 -0400
Local: Thurs, Oct 28 2010 2:08 pm
Subject: Re: Images in autodoc?
My interest is general improvement of Clojure documentation.  At the
conj, I spoke with Zack Kim about helping to improve the state of the
documentation.  My goal was to contribute additional documentation for
vars that are lacking, as well as clarifying some of the more
confusing doc strings (actually as a result of our talk, Zack is
adding some community features to ClojureDocs where we can all comment
and discuss doc string and submit possible revisions).  As I started
looking over the docs, it occurred to me that it would be nice to be
able to format the strings (code formatting, bold, italics, lists,
links, etc.), as well as add images where appropriate (I thought it
might be helpful to have some images for describing how zippers work,
for example).

I wouldn't mind having these features for my own projects, but I think
that Clojure as a whole could benefit from these improvements;
anything to make it easier for newcomers to get up to speed.

Chris

To post a message you must first join this group.
You do not have the permission required to post.
More options Oct 30 2010, 8:04 am
From: Ryan Waters <ryan.or...@gmail.com>
Date: Sat, 30 Oct 2010 07:04:36 -0500
Local: Sat, Oct 30 2010 8:04 am
Subject: Re: Images in autodoc?
+1 on the side of enhancing clojure's core documentation

On Thu, Oct 28, 2010 at 1:08 PM, Chris Maier