Idea: standardised way of packaging docs inside jar

[aroemers]

Hi @weavejester,

I was thinking that maybe a good addition to the Clojure documentation ecosystem would be to have a standardised way of including project documentation inside the project artefact (JAR). This documentation could then be searched and read locally (and offline!), and could also be aggregated on any of the community websites. So, in short, a kind of Ruby's rdoc for Clojure.

I think the output of Codox is great for this. Maybe a good standard would be to put this in a META-INF/codox directory?

How do you feel about this? Does something like this exist already, and did I just miss it?

[weavejester]

Why not just generate the documentation on the fly? So long as the original source files exist in the jar, the documentation can be generated from it.

[aroemers]

Two reasons I can think of:

1. The doc directory is normally not packaged;
2. I don't want to generate the docs myself, having them generated already is quicker.

[weavejester]

If the proposal is to add a META-INF/codox directory, then a META-INF/doc directory could easily be added instead in order to package the doc directory.

Generating the docs might take a second or two longer, but they can be easily cached, so in practice it wouldn't matter much.

The advantage of generating the documentation on the fly is that the end user can choose the format, style, etc. and isn't affected by bugs in earlier versions of the software.

[aroemers]

A standard (default) way of packaging the doc (sources) in META-INF/doc might be a good solution.

I've put the my initial question/idea on Clojure Google Groups as well, so we can see how others think about this.