Codox with Clojuresque

[Matt Bossenbroek]

I've seen a couple of references that codox is supported in clojuresque, but I can't figure out how to use it.

I'm migrating a project from leiningen and was wondering how to get the new build to generate docs.

Could you help point me in the right direction?

Thanks,

Matt

[Meikel Brandmeyer]

Hi,

Am 13.12.2013 20:16, schrieb Matt Bossenbroek:
> I've seen a couple of references that codox is supported in clojuresque,
> but I can't figure out how to use it.

The task is named "clojuredoc" and builds the documentation into
build/docs/clojuredoc. You can create a doc jar like so:

task clojuredocJar(type: Jar) {
classifier = "javadoc"
from project.clojuredoc.outputs
}

Please note: the used codox version most likely needs some update. Also
this feature is not very well tested. Let me know in case there is trouble.

> I'm migrating a project from leiningen and was wondering how to get the
> new build to generate docs.

If you need any support, please let me know. However I have some
troubled health at the moment. It might take a bit before I can reply.

> Could you help point me in the right direction?

Hope that helps.

Meikel

--
Meikel Brandmeyer
Clojure Trainings
Kastellstraße 3
63526 Erlensee
http://kotka.de
USt.-Id: DE 285 667 417

[Matt Bossenbroek]

Unfortunately it didn't seem to work. I have about a dozen source files and it gave the message: 'Could not generate documentation for xyz.core' for about half of them.

It didn't give a reason why - usually codox would give an error message if it couldn't compile something.

And ultimately, nothing was generated - even for the files that had no error message.

Also, how do I specify options to pass to codox? I had been using :include, :src-dir-uri, and :src-linenum-anchor-prefix.

Thanks,

Matt

[Meikel Brandmeyer]

Hi,

Am 16.12.2013 19:48, schrieb Matt Bossenbroek:
> Unfortunately it didn't seem to work. I have about a dozen source files
> and it gave the message: 'Could not generate documentation for xyz.core'
> for about half of them.
>
> It didn't give a reason why - usually codox would give an error message
> if it couldn't compile something.

Obviously the codox version used in clojuresque needs a serious update.
However I looked at the code. The only point I can imagine that
something bad happens, when the namespaces are required. It is done with
:reload in codox, which I don't consider the best idea in this use case,
but for vast majority of code this should not matter.

> And ultimately, nothing was generated - even for the files that had no
> error message.

This is rather strange.

> Also, how do I specify options to pass to codox? I had been using
> :include, :src-dir-uri, and :src-linenum-anchor-prefix.

I will add an option to do that in the next version.

[Meikel Brandmeyer]

Hi,

Am 16.12.2013 22:47, schrieb Meikel Brandmeyer:

> I will add an option to do that in the next version.

I have to mention, that this is a rather not-so-well tested part of
clojuresque and up to now I didn't get any feedback on it. So if you
feel something is missing, please speak up.

[Matt Bossenbroek]

I think those cover most of the options available (there aren't many). I think the only other one was to explicitly exclude specific files.

Thanks,

Matt

[Meikel Brandmeyer]

Hi Matt,

Am 16.12.2013 23:11, schrieb Matt Bossenbroek:
> I think those cover most of the options available (there aren't many). I
> think the only other one was to explicitly exclude specific files.

Things like excluding files is done via source sets in gradle. I would
not expose this as a codox option. For the other options I will probably
just add a option map which is passed verbatim.

[Meikel Brandmeyer]

Hi,

Am 16.12.2013 23:11, schrieb Matt Bossenbroek:

> I think those cover most of the options available (there aren't many). I
> think the only other one was to explicitly exclude specific files.

You might want to check out the 1.6.0-SNAPSHOT which is short before the
new release now. I updated to codox 0.6.6 and added the options you
mentioned. A possible configuration for one of my projects could look
like this:

clojuredoc {
sourceDirectoryURI =
"https://bitbucket.org/kotkade/schnorres/src/v${project.version}/"
linenumAnchorPrefix = "cl-"

exclude "**/some-specific.clj"
}

Kind regards

[Meikel Brandmeyer]

Hi,

Am 22.12.2013 02:02, schrieb Meikel Brandmeyer:

> clojuredoc {
> sourceDirectoryURI =
> "https://bitbucket.org/kotkade/schnorres/src/v${project.version}/"
> linenumAnchorPrefix = "cl-"
>
> exclude "**/some-specific.clj"
> }

BTW, filtering works also by namespace.

clojuredoc {
excludeNamespace "**.some-prefix-*'
}

This would only filter on the doc task. If you wanted to filter in
general for everything (compilation &c), you could do the same on the
source set:

sourceSets {
main {
clojureExcludeNamespace "**.some-prefix-*"
}
}

Note the "clojure" prefix there. Unfortunately I cannot put this on the
clojure sub category of the source set for technical reasons.

Hope that helps.

[Matt Bossenbroek]

Hi, sorry for the long delay - I was traveling for the holidays.

I tried 1.7.0 - it appeared to be the most recent version available.

I added this to build.gradle:

clojuredoc {

sourceDirectoryURI = "https://github.com/Netflix/PigPen/blob/master/"

linenumAnchorPrefix = "L"

}

And this is what I got:

:clojuredoc

Could not generate documentation for pigpen.core

Could not generate documentation for pigpen.exec

Could not generate documentation for pigpen.io

Could not generate documentation for pigpen.join

Could not generate documentation for pigpen.local

Could not generate documentation for pigpen.pig

There are a number of other files that it didn't mention one way or the other in the output, but I don't see any docs for them either. I'm new to gradle, so please let me know if I'm just doing it wrong entirely :)

Also, what would the configuration look like if I only want to include specific files? With the leiningen version, I used this:

:codox {:include [pigpen.core]}

What would that look like using clojuresque? I have the code organized so that users only require one namespace, so I really only need docs for that.

Thanks,

Matt

[Meikel Brandmeyer]

Hi,

On Mon, Jan 06, 2014 at 12:37:11PM -0800, Matt Bossenbroek wrote:

> There are a number of other files that it didn't mention one way or
> the other in the output, but I don't see any docs for them either. I'm
> new to gradle, so please let me know if I'm just doing it wrong
> entirely :)

You obviously depend on the output of the java compilation. But you
don't add it to the classpath of the clojure related tasks. Fortunately
the doc task inherits this from the compile task. So it is sufficient to
fix the classpath for the compile task. Without this, the require of the
namespaces fails and the documentation cannot be generated.
Unfortunately codox swallows the exception. This is not very helpful and
actually causes a bug in that gradle doesn't notice that the task
failed. I will change that in the next release.

Filtering is done on the source set for all tasks or the individual
tasks. Here you want the latter: the other namespace should still be
included in the jar, but only for core the documentation is generated.
So you put the filter on the doc task. You can filter be filename or by
clojure namespace.

I attached a diff for the build.gradle on github. With the patch things
work for me.

Hope this helps.

[Matt Bossenbroek]

Works perfectly - you rock!

Thanks,

Matt

Attachments:

- build.gradle-working.diff

[Meikel Brandmeyer]

On Wed, Jan 08, 2014 at 01:09:19PM -0800, Matt Bossenbroek wrote:
> Works perfectly - you rock!

You are welcome. :)