search

asciidoctor / asciidoclet

:clipboard: A Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
https://github.com/asciidoctor/asciidoclet
Apache License 2.0
133 stars 40 forks source link

Official asciidoclet Gradle sample #44

Closed msgilligan closed 8 years ago

msgilligan commented 8 years ago

It would be nice if there were a more-or-less official sample demonstrating use of asciidoclet in a Gradle project.

I did find this one: https://github.com/JGrenier/asciidoclet-sample

(One of the reasons I ask for this is that it's very useful for comparison purposes when you think you've found an issue.)

johncarl81 commented 8 years ago

We do have a pretty detailed example in the README, was that insufficient?

msgilligan commented 8 years ago

The README is good, but I want something that I can git clone and run. (And compare to my build, update to newer versions of Gradle, Asciidoctor, etc. -- and even send pull requests.)

johncarl81 commented 8 years ago

Understandable, and I've heard some grumblings about the README being too sparse. What do you think about a few example projects, maybe one for each type of common build: Maven, Gradle, Ant?

msgilligan commented 8 years ago

I use Gradle for almost all my projects, so that is the only one I'm personally interested in. I'm sure a Maven sample would be popular, too. I'm an old Ant-jockey but I almost never see projects built with Ant anymore.

Sample projects are only useful if they're kept up-to-date with the latest versions of the build tools and dependencies. If enough people are using the samples, you're likely to get pull requests updating them to newer versions -- or at least issues opened when something breaks. For example, An Ant sample might just go stale.

msgilligan commented 8 years ago

It would also be nice to provide a list of real, external projects that are using AsciiDoclet. I'm experimenting with it to document a Bitcoin JSON-RPC client, but would love to see some great examples of other projects that have used it to document (large) APIs.

johncarl81 commented 8 years ago

I believe we're accomplished this.