Images in autodoc?
Chris
can? I'm interested in adding explanatory diagrams to function
documentation as opposed to adding things like logos to the HTML
pages.
Thanks,
Chris
Tom Faulhaber
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
Andrew Gwozdziewycz
> It's on the roadmap.
>
> 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]
...)
Chris
> 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.
(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
Chris
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
Andrew Gwozdziewycz
> 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.
> On Oct 26, 6:05 am, Chris <christopher.ma...@gmail.com> wrote:
>> 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
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clo...@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+u...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
Chris
> I like that idea, especially if it could be extended to reference other code:
anything else?
Chris
Andrew Gwozdziewycz
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.
Eric Schulte
LaTeX equations. Which are increasingly easy to render in HTML
(e.g. http://www.mathjax.org/).
-- Eric
>
> Chris
Andrew Gwozdziewycz
I guess the problem is actually making a patch to autodoc to do this all :)
Tom Faulhaber
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:
> > 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
Chris Maier
> 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
pretty readable, myself, particularly if all the link addresses are
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
Andrew Gwozdziewycz
<christop...@gmail.com> wrote:
> On Tue, Oct 26, 2010 at 1:08 PM, Tom Faulhaber <tomfau...@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
> pretty readable, myself, particularly if all the link addresses are
> 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
2. links (internal. for external links, just use fully qualified URI)
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.
Timo Mihaljov
> 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
hyperlinks.
--
Timo
Andrew Gwozdziewycz
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
Chris Maier
>> 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
>> hyperlinks.
That is slick.
If there's any way I can help out, too, sign me up.
Chris
Andrew Gwozdziewycz
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.
[1]: http://github.com/apgwoz/clj-docup
Ryan Waters
(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
Christopher Petrilli
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
| petr...@amber.org
Eric Schulte
> 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
formats that support documentation links. It's a nice low-overhead way
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
Tom Faulhaber
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
Andrew Gwozdziewycz
> 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 clo...@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+u...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
Chris Maier
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