+1 on the side of enhancing clojure's core documentation
On Thu, Oct 28, 2010 at 1:08 PM, Chris Maier
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 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
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
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.
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
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
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
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
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
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
--
You received this message because you are subscribed to the
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
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
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
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
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
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
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
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
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
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.
Thanks,
Chris
--
You received this message because you are subscribed to the Google
Groups
20 matches
Mail list logo
