I think I’ve found all the existing content sources and incorporated them in to the Antora-built site.
Sources: * tomee docs (moved to antora structure) (versions master = 8.0, 7.1, and 7.0) * tomee examples (script to copy/rename to antora structure for appropriate language) (version master = 8.0 only) * tomee-site-generator (converted to adoc and moved to antora structure) (currently labeled version 0.1) * tomee-site (converted to adoc and moved to antora structure) (currently labeled version 0.0) Comparing the live site-map.xml and the ones generated for the Antora-built site, there is one file missing (index-old.html http://tomee.apache.org/examples/index-old.html) which I don’t think is necessary or appropriate to move, and 119 new files that didn’t appear in the existing site. They are listed in tomee@antora docs/new-not-old-index.txt. The old-new diffs are only whether some version of the file stem appears in each site, I haven’t tried to figure out how to compare which versions each page appears in. So far I’ve made no attempt to incorporate javadoc. If you are not quite familiar with Antora structure looking at the preview at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html> will probably help understand the questions. In particular in the lower left corner there’s the “component drawer” where you can select the component and version to view. Questions: * How should the content be arranged into components and versions? ** current state: *** There are two components, tomee and examples. *** The tomee component has versions 8.0, 7.1, and 7.0 (from tomee/docs) and 0.1 (from tomee-site-generator) and 0.0 (tomee-site) *** The examples component has versions 8.0-en, 8.0-sp, 8.0-pt for the different languages ** Sub-questions: *** Is all of the content I’ve put under tomee actually version specific, or is there some content that is conceptually unversioned (general information about tomee, perhaps). This could be separated into a separate unversioned component. *** Is some or all of the content I’ve put in 0.1 and 0.0 actually associated with a real version such as 1.7 or OpenEJB v??? *** Is there a need to maintain earlier versions of the examples documentation, or is just “current” enough? It looks like there are earlier examples directories in the 7.1.x and 7.0.x branches, and it would certainly be possible to convert them and include them in the site, but I think that might make the site harder to use and less informative. * How should the content with a version be organized on the source tree and in the navigation? The source-tree questions certainly don’t need immediate answers. ** Source tree: Antora source structure is modules/<module-name>/pages/<path-to-adoc>. The ‘default’ module name is ‘ROOT’, which is what I’ve used. Antora can deal directly with content in subfolders of ‘pages’ (some of which has appeared reflecting the original arrangement) and additional modules (useful to keep each module a manageable size). *** To what extent would it be useful to break the content up into modules? *** The examples are grouped in the navigation but are flat in the file system. Would it be appropriate to reflect the doc grouping in the file system layout? ** Navigation current state: *** The 8.0, 7.1, and 7.0 tomee versions have navigation adapted from documentation.adoc This seems more or less reasonable for now. *** The 0.1 and 0.0 tomee versions have navigation generated by just listing all the pages. *** The examples have navigation adapted from the existing examples navigation. ** Sub-questions: *** How should the 0.1 and 0.0 be organized? Is there an existing page that is a starting point, as documentation.adoc is for more current content? *** What other changes or refinements are appropriate? ** Other: *** can the conglomerated javadoc be generated by maven rather than the custom script now used? Starting with a javadoc jar seems simpler than building it as part of the site generation. ===== Where is it? preview: https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html> git repos: tomee <https://github.com/djencks/tomee> (antora, antora-tomee-7.1.x, antora-tomee-7.0.x) Some instructions are in docs/INSTRUCTIONS.adoc tomee-site-generator <https://github.com/djencks/tomee-site-generator> (antora) tomee-site <https://github.com/djencks/tomee-site> (antora) Thanks! David Jencks > On Feb 8, 2020, at 10:32 PM, David Jencks <david.a.jen...@gmail.com> wrote: > > I now have the adoc content from master, 7.1.0.x, 7.0.0.x, the example > README.adoc from master (sorted by language), and the formerly .md files from > tomee-site-generator. > > <all the history snipped>
