[hibernate-dev] Documentation project - asciidoctor + CSS

[Steve Ebersole]

I'd prefer to just not do the docbook phase; it's just unnecessary overhead
during a build.

I'd be very surprised if the asciidoctor tool chain does not allow us to
plugin CSS as well.  Granted we'd have to adjust the CSS for the
styles/classes used by the asciidoctor output.  I'll ask around.

On Wed, Dec 2, 2015 at 5:29 AM Vlad Mihalcea <mihalcea.vlad at gmail.com>
wrote:

> Hi,
>
> I started migrating the 5.0 docbook documentation to asciidoctor, and,
> because there wasn't any converter for such a task, I wrote a small shell
> script which uses pandoc.
>
> I managed to generate the asciidoc files from the current docbook, by using
> the html format the docbook generates. The resulting asciidoc files need
> some minor changes, but all in all it's still better than doing it
> manually.
>
> I wrote a new gradle task to take the asciidocs from the mapping guides and
> generate the html documentation, while applying the Hibernate CSS.
>
> I saw there are some common XSLTs that were applied in order to add the
> Hibernate logo and the Copyright info to every HTML page.
>
> If you want to take a look on it, this is my branch with the latest changes
> I've made:
>
> https://github.com/vladmihalcea/hibernate-orm/tree/feature/asciidocs
>
> >From a discussion I found on the asciidoctor GitHub page (
> https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/52 ), I
> realized that we could create a tool-chain like this:
>
> - we write all docs in asciidoctor and use the asciidoc-gradle-plugin to
> convert those to docbook
> - from docbooks we can use the current jdocbook plugin to generate the
> single HTML, multi-html and PDFs and use the current XSLTs.
>
> With this workflow, the styling of the docs is already resolved, since the
> jdocbook configs can take care of it already. This could be a first phase
> until we figure out how we can generate everything we want and customize it
> all without having the intermediate docbook phase.
>
> Or, we can just forget about docbook and do our best to generate everything
> using the asciidoctor tool-chain, even if it might not be a straightforward
> task.
>
> Let me know what you think?
>
> Vlad
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>