Thanks for the encouragement! I need someone to tell me where the doc generation code is, and ideally how it is configured and run. I’ve moved a lot of the partially generated docs so this code will need to be updated.
Thanks David Jencks > On Mar 12, 2020, at 2:36 AM, Zoran Regvart <zo...@regvart.com> wrote: > > 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 > <mailto:david.a.jen...@gmail.com>> wrote: >> >> I went ahead and opened an issue CAMEL-14698 >> <https://issues.apache.org/jira/browse/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
