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 <david.a.jen...@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
