Is it possible to add images to autodoc-generated pages like javadoc
can? I'm interested in adding explanatory diagrams to function
documentation as opposed to adding things like logos to the HTML
pages.
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:
> Is it possible to add images to autodoc-generated pages like javadoc
> can? I'm interested in adding explanatory diagrams to function
> documentation as opposed to adding things like logos to the HTML
> pages.
On Tue, Oct 26, 2010 at 3:50 AM, Tom Faulhaber <tomfaulha...@gmail.com> wrote: > 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.
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.
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:
> 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.
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.
> 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 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+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
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 > clojure+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
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/).
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 > clojure+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
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:
> 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
> > clojure+unsubscribe@googlegroups.com
> > For more options, visit this group at
> >http://groups.google.com/group/clojure?hl=en
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 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?
<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 > 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:
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.
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 hyperlinks.
On Tue, Oct 26, 2010 at 4:44 PM, Timo Mihaljov <noid....@gmail.com> wrote: > 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 > hyperlinks.
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 > clojure+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
> 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 >> hyperlinks.
That is slick.
If there's any way I can help out, too, sign me up.
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.
<christopher.ma...@gmail.com> wrote: >> 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 >>> hyperlinks.
> That is slick.
> If there's any way I can help out, too, sign me up.
> 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 > clojure+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
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 ; )
On Tue, Oct 26, 2010 at 12:08 PM, Tom Faulhaber <tomfaulha...@gmail.com> wrote: > 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: >> 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 >> > clojure+unsubscribe@googlegroups.com >> > For more options, visit this group at >> >http://groups.google.com/group/clojure?hl=en
> -- > 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+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
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.
On Wed, Oct 27, 2010 at 1:09 PM, Ryan Waters <ryan.or...@gmail.com> wrote: > 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
> On Tue, Oct 26, 2010 at 12:08 PM, Tom Faulhaber <tomfaulha...@gmail.com> wrote: >> 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: >>> 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 >>> > clojure+unsubscribe@googlegroups.com >>> > For more options, visit this group at >>> >http://groups.google.com/group/clojure?hl=en
>> -- >> 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+unsubscribe@googlegroups.com >> For more options, visit this group at >> http://groups.google.com/group/clojure?hl=en
> -- > 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+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
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 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.
> On Wed, Oct 27, 2010 at 1:09 PM, Ryan Waters <ryan.or...@gmail.com> wrote: >> 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
>> On Tue, Oct 26, 2010 at 12:08 PM, Tom Faulhaber <tomfaulha...@gmail.com> wrote: >>> 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: >>>> 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 >>>> > clojure+unsubscribe@googlegroups.com >>>> > For more options, visit this group at >>>> >http://groups.google.com/group/clojure?hl=en
>>> -- >>> 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+unsubscribe@googlegroups.com >>> For more options, visit this group at >>> http://groups.google.com/group/clojure?hl=en
>> -- >> 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+unsubscribe@googlegroups.com >> For more options, visit this group at >> http://groups.google.com/group/clojure?hl=en
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.
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 > clojure+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
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.
On Thu, Oct 28, 2010 at 1:09 PM, Andrew Gwozdziewycz <apg...@gmail.com> wrote: > 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 >> clojure+unsubscribe@googlegroups.com >> For more options, visit this group at >> http://groups.google.com/group/clojure?hl=en
> -- > 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+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
<christopher.ma...@gmail.com> wrote: > 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.
