Codox: an API doc generator for Clojure

[James Reeves]

Hi folks,

In order to generate the documentation for Ring and Compojure, I
created Codox after being unable to get Autodoc working.

Codox is pretty simple, but should work out of the box, and hopefully
looks quite nice. Here are a couple of examples:

http://mmcgrana.github.com/ring/
http://weavejester.github.com/compojure/

Options are limited so far, but patches to add options or improve the
formatting are welcome.

The project page is here:

https://github.com/weavejester/codox

- James

[Shantanu Kumar]

+1 This is pretty neat! (I too couldn't get Autodoc working in the
past several months.)

Regards,
Shantanu

On Dec 26, 10:29 pm, James Reeves <jree...@weavejester.com> wrote:
> Hi folks,
>
> In order to generate the documentation for Ring and Compojure, I
> created Codox after being unable to get Autodoc working.
>
> Codox is pretty simple, but should work out of the box, and hopefully
> looks quite nice. Here are a couple of examples:
>

> http://mmcgrana.github.com/ring/http://weavejester.github.com/compojure/

[Gert Verhoog]

I love it, thanks, and I got it running in about 10 seconds:

lein install plugin codox 0.3.1
lein doc

Question: One of my ns docstrings is a fair amount of text which is rendered as a really long line (because codox puts it inside a <pre>...</pre> element). How would you deal with longer documentation strings? Would I need to insert manual line breaks or is there a better way?

cheers,
gert

> --
> 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

[Meikel Brandmeyer]

Hi,

Am 26.12.2011 um 22:23 schrieb Gert Verhoog:

> Question: One of my ns docstrings is a fair amount of text which is rendered as a really long line (because codox puts it inside a <pre>...</pre> element). How would you deal with longer documentation strings? Would I need to insert manual line breaks or is there a better way?

Maybe we could agree on something like Markdown to render docstrings?

Sincerely
Meikel

[James Reeves]

On 26 December 2011 21:23, Gert Verhoog <m...@gertalot.com> wrote:
> Question: One of my ns docstrings is a fair amount of text which is rendered as a really long line (because codox puts it inside a <pre>...</pre> element). How would you deal with longer documentation strings? Would I need to insert manual line breaks or is there a better way?

Because docstrings can be read at a REPL with the `doc` macro, it's
common practise to break up docstrings onto multiple lines.

It might be an idea to figure out some standard syntax we could use,
like Markdown, that could be used for formatting docstrings.

- James

[Laurent PETIT]

Hello,

Is it in your roadmap to provide links to source code of the functions ?
I know this is a border line feature between codox/autodoc and marginalia, but it could be proven useful, even for API documentation (no API is perfectly documented)

2011/12/26 James Reeves <jre...@weavejester.com>

- James

[Stefan Kamphausen]

Hi,

On Tuesday, December 27, 2011 1:18:52 PM UTC+1, James Reeves wrote:

It might be an idea to figure out some standard syntax we could use,
like Markdown, that could be used for formatting docstrings.

IMHO the missing homoiconicity of docstrings in all flavors of Lisp that I worked with always was a tiny itch.

It would be very nice, if docstrings were a 'real' datastructure.

Kind regards,
Stefan

[Tom Faulhaber]

Hi All,

This makes me feel quite embarrassed that autodoc hasn't seen a
release for non-core/contrib projects in so long. I apologize for
that. (Insert all the usual "life has been crazy... " caveats here.) I
hate seeing smart people having to recreate stuff just cause it's
taking me a long time to get around to it.

I had already put Autodoc on my "Christmas lull to-do list" and am
closing in on a new release. Depending how things go on disentagling
the recursive loop I've set up with Leiningen, I should have a 0.9.0
out this week.

Nicely, I think that Codox and Autodoc should coexist pretty happily
and Codox's life is somewhat simplified by not having to deal with the
core/contrib craziness (and not, I think, having to deal with
documenting multiple versions in the same package).

Tom

On Dec 26, 9:29 am, James Reeves <jree...@weavejester.com> wrote:
> Hi folks,
>
> In order to generate the documentation for Ring and Compojure, I
> created Codox after being unable to get Autodoc working.
>
> Codox is pretty simple, but should work out of the box, and hopefully
> looks quite nice. Here are a couple of examples:
>

> http://mmcgrana.github.com/ring/http://weavejester.github.com/compojure/

[Fogus]

> It might be an idea to figure out some standard syntax we could use,
> like Markdown, that could be used for formatting docstrings.

My vote is for Markdown as well.