Hi David, this all looks very good to me. I think less file copying/duplication we have the better. Keep up the good work!
zoran On Wed, Mar 11, 2020 at 11:27 PM David Jencks <david.a.jen...@gmail.com> wrote: > > 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 > -- Zoran Regvart
