Generate antora documentation module

[c835722]

Hi. Thanks for this project and the opportunity to particpate in feature requests.

Feature objective: docToolchain integration with Antora such that docToolchain would generate an Antora documentation module.

End game objective: Architecture, Dev, Test projects documents housed under a single Project website. i.e. I envisage a site like https://doc.owncloud.org/server/index.html but also containing the project Architecture work products, models and diagrams.

[rdmueller]

Great feature request and we are indeed already working on such a feature. Currently, we use jekyll to combine all docs into a full website since jekyll even has some more features than antorra. An example is https://docs-as-co.de

And Andreas works on an Antora version of arc42: https://blog.anoff.io/2019-02-15-antora-first-steps/

We'll keep you updated!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Just add a small comment to keep it open. Thank you for your contributions.

[PacoVK]

What is the actual status here? I would like to take a look into this issue, but honestly need more input here :) Basically the overall question is if the main goal would be to integrate an Antora template or even be able to auto-generate Antora module(s) from the docs. For the latter i could envision to have a concept similar to github-pages where the actual result (the antora module) could be integrated into any existing Antora stack with a reference in playbook.yml to this particular branch. That may be validated if that would be possible.

[rdmueller]

the status is that we don't have enough time to implement everything. But if you want to add features to docToolchain, feel free to propose your own.

I never managed to use antora and tehrefore don't know about antora modules, but I could imagine two interesting features:

• let jBake render an Antora document structure
• use Antora instead of jBake

What do you think?

[PacoVK]

alright, thanks for the insights :) Just wanted to ensure that nobody is already working on that, since some older comments stated that. Ofc i see time is always a big constraint. I will wrap my head around and come up with a propsal, i basically need to dig a bit deeper into jBake first to be able to come up with a evidence-based proposal. Will use this issue to keep you posted and to have some discussions on how to proceed 👍

[rdmueller]

I can help you with the jbake part...

[PacoVK]

I think that would be great 👍

[rdmueller]

let's try to sketch some infos here. Maybe we can turn it into some docs later.

jBake first parses all pages, converts them and stores the results in an inmemory database.

It then uses the templates to render the final pages. Execute ./dtcw copyTheme to copy the default jBakeTheme to your respository (src/site/templates).

Those templates are gsp-templates - html mixed with groovy code. Groovy is Java++ - you can use all your java knowledge, but also have some shortcuts available. This way, you can do everything in those templates, even access the filesystem or internet if needed :-)

Within the templates, there are three important Maps:

• published_content contains all data about the pages - all pages
• content contains eerything about the current page
• config contains doctoolchainConfig.groovy

If you need to build up some kind of cache between pages, feel free to add this content to one of those maps - they will be accessible from all templates.

To debug templates, you can use try-catch blocks and output information via System.out.println (to the shell) or just render the information within the page.

I guess that's it - everything you need to know about jBake