[Docs] Usefulness of potential Antora capability

[David Jencks <da...@gmail.com>]

My understanding of the component doc generation process is that

* Something partially generates the component .adoc files from javascript, in the component maven project; these are checked into git somehow
* gulp is configured to find and copy all these .adoc files to a central location, and they are checked into git there.
* something (gulp?) generates the component nav.adoc file
* something runs Antora.

There are a couple of Antora issues suggesting that non-standard source layouts could be useful, and I’m wondering if collecting documentation out of multiple maven projects might be one such case.  To see what was possible and easy I wrote some code… #520 <https://gitlab.com/antora/antora/issues/520>

As it is today, the “copy to a central location” step could be replaced by a (presumably generated) components/antora.yml configuration like

source_map
  camel-activemq/src/main/docs: modules/components/pages
… (one line for each component)

Does having an Antora capability like this seem at all useful, or is the current “copy and check in” approach better?  What’s there now is just what I thought of first and was easy to implement, no doubt many improvements are possible.

Thanks for any comments,
David Jencks

Re: [Docs] Usefulness of potential Antora capability

[Zoran Regvart <zo...@regvart.com>]

Hi David,
The ability to map src/main/docs to the Antora expected directory
structure, as you're proposing looks better to me. This would save us
from having to do those "regen" commits when we make a change to the
component documentation and commit without running the build in
`docs/`. Thank you for doing that :)

Perhaps for others that might be interested in this, let me step
through the process as I know it:

We have a set of annotation processors and Maven plugins that take the
Java source code and update parts of the Asciidoc files in the
`components/`, this is run at the build time of Camel. This process is
somewhat involved and it not only generates the update Asciidoc files
in `components/*/src/main/docs` but also updates the catalog files,
regenerates the Spring Boot starters and I'm probably missing
something.

In the `docs/` we have a Gulp project that's being run as the last
project in the Maven reactor using the frontend-maven-plugin that
copies the Asciidoc files from `components/*/src/main/docs` from
select places in the `core/` and regenerates the "components"
component ROOT module's `nav.adoc`. There's a similar process for
copying and updating the EIP documentation in the "user-manual"
component. Important bit in this step is adding the "page-source"
Asciidoc attribute which points to the source file.

We do all this copying because Antora disabled git symlink support[1]
and we could no longer use git symlinks but had to copy the files into
the Antora structure.

We also have the Antora documentation in two sub-projects: camel-k[2]
and camel-quarkus[3].

The website where the documentation is published is run from the
camel-website[4] git repository, where we have the forked default
Antora UI theme, the Hugo static site generation and Antora
documentation build.

zoran

[1] https://gitlab.com/antora/antora/issues/188
[2] https://github.com/apache/camel-k/tree/master/docs
[3] https://github.com/apache/camel-quarkus/tree/master/docs
[4] https://github.com/apache/camel-website/

On Tue, Nov 5, 2019 at 8:18 PM David Jencks <da...@gmail.com> wrote:
>
> My understanding of the component doc generation process is that
>
> * Something partially generates the component .adoc files from javascript, in the component maven project; these are checked into git somehow
> * gulp is configured to find and copy all these .adoc files to a central location, and they are checked into git there.
> * something (gulp?) generates the component nav.adoc file
> * something runs Antora.
>
> There are a couple of Antora issues suggesting that non-standard source layouts could be useful, and I’m wondering if collecting documentation out of multiple maven projects might be one such case.  To see what was possible and easy I wrote some code… #520 <https://gitlab.com/antora/antora/issues/520>
>
> As it is today, the “copy to a central location” step could be replaced by a (presumably generated) components/antora.yml configuration like
>
> source_map
>   camel-activemq/src/main/docs: modules/components/pages
> … (one line for each component)
>
> Does having an Antora capability like this seem at all useful, or is the current “copy and check in” approach better?  What’s there now is just what I thought of first and was easy to implement, no doubt many improvements are possible.
>
> Thanks for any comments,
> David Jencks



-- 
Zoran Regvart