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

Include default css #19

Closed johncarl81 closed 10 years ago

johncarl81 commented 10 years ago

As it stands, asciidoctor's rendered output relies on css for styling elements. Including this in the generated asciidoclet source will bring the generated output closer to what is intended with Asciidoctor's output.

Should we also include the ability to add additional css?

benevans commented 10 years ago

FWIW I think it would be sufficient just to have a good default stylesheet that renders the Asciidoctor output nicely. Users can always modify the default one and pass it to the -stylesheet option.

johncarl81 commented 10 years ago

Agreed, I wonder if we could just include the detault Asciidoctor stylesheet and call this one done. Btw, this came from the following conversation: http://discuss.asciidoctor.org/asciidoclet-table-css-not-included-td1687.html

benevans commented 10 years ago

I wonder if we could just include the default Asciidoctor stylesheet and call this one done.

I'm afraid it's not that simple, javadoc's own default stylesheet has many classes that don't exist in the Asciidoctor stylesheet, so lots of things break if the expected classes aren't there.

At a minimum you could start with the javadoc stylesheet and tweak it to make Asciidoctor's output look nicer. This is what pegdown-doclet does.

Another approach might be to combine javadoc and Asciidoctor's default stylesheets, and fix up any conflicts, to get javadoc that looks more like normal Asciidoctor output. I started playing with something like this recently, but struggled as I don't know CSS that well. Might revisit this if I have time.

johncarl81 commented 10 years ago

Im not sure what the correct approach is. Possibly we need to pull out the missing css elements into a stripped down version of Asciidoctor's style sheet (for instace: we need table css). I encourage you to look at this more, even if CSS isn't your forte.

By the way, pegdown-doclet was one inspiration for Asciidoclet.

benevans commented 10 years ago

Here's a work-in-progress using the Java8 javadoc stylesheet plus most of Asciidoctor's default stylesheet: http://jsfiddle.net/benevans/wed9w/9/embedded/result/

Turned out to be not as hard as I feared, just commenting out a few parts of the Asciidoctor CSS gets you 90% there.

johncarl81 commented 10 years ago

Wow, I love the results. I wonder how this plays with earlier versions of Java Javadocs. Can you share in a PR?

benevans commented 10 years ago

Should be fixed in the above PR, please give it a try. The new stylesheets keep most of the default javadoc styling, just adding enough so that tables and examples etc look right.