I went ahead and opened an issue CAMEL-14698 <https://issues.apache.org/jira/browse/CAMEL-14698> and implemented some of what I am thinking of, see links in the issue.
I think there may be some inconsistencies or mistakes in the gulpfile or how it relates to the content…. - Several sources are copied into both components and user-manual, but are indexed into nav files in only one. I’d expect they should be in only one place, where they are indexed. In particular… core/camel-base/src/main/docs/*.adoc has only one file, a component. Also it doesn’t appear to have any generated parts. Could it simply be a static file in docs/component/modules/ROOT/pages? I don’t think it’s referenced in user-manual, so perhaps it doesn’t need to be there. core/camel-core-languages/src/main/docs/*.adoc is copied into both component and user-manual and, actually indexed nowhere. It looks like it’s supposed to be indexed in user-manual, so I changed it to be indexed there in my branch. I haven’t been able to locate how code generation happens; since the location of many of the partially-generated .adoc files has changed this will need to be updated. Does generation go through the json files that appear to have much of the same information as in the tables? Is anything except table content generated? Asciidoctor/antora can already create tables from csv; I’m wondering if there’s a way to reduce the amount of generation. Thanks, David Jencks > On Mar 11, 2020, at 2:32 AM, Zoran Regvart <zo...@regvart.com> wrote: > > Hi David, > I'll try to answer inline > > On Tue, Mar 10, 2020 at 9:10 PM David Jencks <david.a.jen...@gmail.com> wrote: >> First question: Is there a reason to maintain this copy-to-antora-structure >> step rather than using native antora capabilities? > > For a significant part of the documentation we rely on code > generation, the way we do things right now is informed by what we have > in place for that. That includes the locations of files and to a > smaller degree the structure of files. Most of what was done was done > to get something working. > >> 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? > > Feel free to propose improvements, what you suggest sounds good to me. > Keep in mind the code generation bits, so even if you move the files > they might reappear because of that. I think it's likely that we need > to touch the code (documentation) generation bits also. > >> —————— >> 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. > > This sounds very promising, thank you for looking into this :) > > zoran > -- > Zoran Regvart
