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

Add support for Asciidoc overview files #20

Closed benevans closed 10 years ago

benevans commented 10 years ago

This patch allows the doclet to process Asciidoc overview files passed in with "-overview".

The doclet only process overview files named *.ad, *.adoc, *.asciidoc or *.txt. Other files will be processed by the standard doclet.

johncarl81 commented 10 years ago

I was just looking at this... why did you close @benevans?

benevans commented 10 years ago

Heh, was just about to explain - something is causing the divs in the overview HTML to be generated incorrectly, e.g. contentContainer and footer divs end up inside the header div.

Will resubmit when I've fixed that.

benevans commented 10 years ago

Seems to be a more general issue so I've opened #21 describing what I've found.

benevans commented 10 years ago

@johncarl81, this change wasn't related to the output issues in #21, should be fine to merge as-is, if you like. Note that #23 needs to be applied as well to solve the output issues.

johncarl81 commented 10 years ago

Looks good. I haven't seen overview files in other doclets.. is this a common approach? Seems useful nonetheless.

benevans commented 10 years ago

Overviews are good for larger projects with many Java packages. If your project's javadoc only has one package, then its package-info.java comment (or package.html) appears on the main index.html page, describing the package. But if there are many packages, then you just get a listing of the packages. Using an overview file means you can put some useful introductory text on the main page.

The standard doclet only understands HTML overview files (with the usual javadoc tags like {@link} etc. It would be a bit inconvenient to do your doc comments in lovely asciidoc then have to drop back down into HTML for the overview!

johncarl81 commented 10 years ago

Beautiful. Thanks @benevans!