I think what I have in mind is complete for ‘latest’ now. There are some broken links from other components and versions into the manual and components latest, but otherwise I’m not aware of any new breakages.
Other changes: - The core language documentation appeared in both the manual and components. I moved it to components. I don’t know if this is a better place than manual, but I’m sure having 2 copies is not a good idea. In components, the languages now appear as a group below the components and data formats. Questions: - Should the dataformats be split into a components module? - There are several eip related pages in the “main” user manual, such as `enterprise-integration-patterns.adoc`. Would these be better logically moved to the rest of the eip pages in the eips module? If so I think it would make the most sense to move the source to the core/camel-core-engine with the partially generated pages, although it would work equally well from Antora’s standpoint to leave them in docs/user-manual and just change the module. - Would it even make sense to have the eip pages in a separate component? Solved (I think): - table generation modified to new enclosing document location. - mojo xref checker replaced with Antora xref checker (I’m not convinced the mojo xref checker works well). - xrefs updated. - eip images moved. - (not actually a problem) example gathering still works: there are no example includes in eips or languages. What next? If there’s general agreement to make these changes, I’ll fix the remaining broken links from other components and, if it seems a good idea, do the same sort of changes for the components version 2 and 3. To try this out, get my camel-website and possibly camel repos, on the issue-14698-rearrange-adocs branch, make sure you have antora 2.3.0-alpha.2 installed, and build using either antora-playbook-basic-local.yml to use your locally checked out camel repo or antora-playbook.yml to use my GitHub branch directly. https://github.com/djencks/camel-website.git <https://github.com/djencks/camel-website.git> https://github.com/djencks/camel.git <https://github.com/djencks/camel.git> Thanks David Jencks > On Mar 12, 2020, at 10:54 AM, Andrea Cosentino <anco...@gmail.com> wrote: > > Yes, It should I guess. > > Il gio 12 mar 2020, 18:52 David Jencks <david.a.jen...@gmail.com> ha > scritto: > >> thanks for the pointers… >> >> Not caused by my changes, but shouldn’t this be like so? >> >> (org/apache/camel/maven/packaging/UpdateReadmeMojo.java) >> private void executeEips() throws MojoExecutionException { >> - // only run if in camel-core >> + // only run if in camel-core-engine >> String currentDir = >> Paths.get(".").normalize().toAbsolutePath().toString(); >> - if (!currentDir.endsWith("camel-core")) { >> + if (!currentDir.endsWith("camel-core-engine")) { >> return; >> } >> >> Did the eip code get moved at some point without this getting updated? >> >> thanks >> David Jencks >> >>> On Mar 12, 2020, at 8:01 AM, Andrea Cosentino >> <ancosen1...@yahoo.com.INVALID> wrote: >>> >>> We had a big effort to be able to setup everything, so before merging >> anything we need to be absolutely sure we won't lost documentation along >> the way. >>> >>> -- >>> Andrea Cosentino >>> ---------------------------------- >>> Apache Camel PMC Chair >>> Apache Karaf Committer >>> Apache Servicemix PMC Member >>> Email: ancosen1...@yahoo.com >>> Twitter: @oscerd2 >>> Github: oscerd >>> >>> >>> >>> >>> >>> >>> On Thursday, March 12, 2020, 03:57:56 PM GMT+1, Claus Ibsen < >> claus.ib...@gmail.com> wrote: >>> >>> >>> >>> >>> >>> Hi >>> >>> The doc generation is in the tooling/maven/camel-package-maven-plugin >>> >>> Just be cautious that the doc generation process also generate >>> metadata such as json files and others that are needed in the >>> components folders. >>> Also it generates/aligns the adoc file in src/main/docs for the >>> components to keep parts up to date. >>> >>> So its only some parts that can be moved, however we want to keep the >>> docs together with the source code, when the doc is about the >>> component. >>> >>> >>> >>> On Thu, Mar 12, 2020 at 3:48 PM David Jencks <david.a.jen...@gmail.com> >> wrote: >>>> >>>> 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 >>> >>>> >>> >>> >>> -- >>> Claus Ibsen >>> ----------------- >>> http://davsclaus.com @davsclaus >>> Camel in Action 2: https://www.manning.com/ibsen2 >> >>
