These days I’m more interested in documentation, and in particular Antora, than
code. I think the camel website is really impressive, and I’m really happy to
see the flurry of UI changes recently.
As I work with Antora, I increasingly think that the largest benefit it brings
is organizational: that by having a consistent relationship between directory
layout and logical documentation organization, with components, modules, and
topics, it simplifies thinking about how to organize documentation.
I have some questions about how some of the documentation source is arranged
and processed, as it doesn’t seem to me to fit with Antora best practices.
I do understand why the component documentation is handled the way it is,
although I hope something simpler will eventually be available.
However, the user-manual documentation seems to me to not take advantage of
several basic antora capabilities, and I wonder why. If I understand the main
camel docs/gulpfile.js, all the .adoc files are copied from 4 locations and put
into the root module of one component:
return src(['../core/camel-base/src/main/docs/*.adoc',
'../core/camel-core-languages/src/main/docs/*.adoc',
'../core/camel-xml-jaxp/src/main/docs/*.adoc',
'../core/camel-core-engine/src/main/docs/eips/*.adoc'])
…
Right now all these user-manual .adocs are copied into an antora structure
before site generation, and IIUC committed for access by Antora. This is
entirely unnecessary. An alternate scheme is to change the directory structure
of the docs where they are, e.g. mv *.adoc modules/ROOT/pages/ so they are
already in an Antora structure, and use a distributed component, i.e. provide
an antora.yml component descriptor in each of these 4 source locations. If
different modules were used for different parts of the docs, some of these “mv”
commands would involve modules other than ROOT.
First question: Is there a reason to maintain this copy-to-antora-structure
step rather than using native antora capabilities?
If I understand the nav generation, two of these subsets (languages and eips)
later need to be separated out for separate sections in the nav.
Second question: To me it would make more sense to put these distinct types of
content into different modules. Is there some reason not to?
If these changes seem like a good idea, or if seeing in detail what the results
would be would be helpful, I’m happy to provide a PR with these changes.
——————
Quite some time ago I proposed a way to have Antora collect files from
scattered locations into an Antora structure, but that didn’t go anywhere.
There’s an Antora issue for a plugin system, which I’ve implemented a proprosal
for (https://gitlab.com/antora/antora/issues/377). Based on this I’ve
implemented a plugin that collects scattered source; it’s a lot better than my
first attempt. If and when this might be usable with a released Antora is
unknown, but it works well to gather the component .adocs.
I’m also working on an index:: block macro asciidoctor extension to collect all
the .adoc files matching a filter and create a list of xrefs, similar to what
the nav-builder code in the aforementioned gulpfile.js does. It’s usable now
in regular pages but needs an Antora modification to work in nav files.
It would be in the indefinite future, but with the reorganizations proposed,
and these extension/plugins, the gulpfile would be unnecessary.
Thanks
David Jencks
