Re: Documentation site

[David Jencks]

Possibly there’s some duplication in the new site:

individual addresses in sitemaps, without translations:
old sitemap page count: 560 old-sitemap-addr.txt
new sitemap page count: 1423 new-sitemap-addr-en-only.txt

comparison of unique page names (without path, source, or version info):
old-not-new count: 1 old-not-new-index.txt
new-not-old count: 119 new-not-old-index.txt

If anyone has ideas how to identify it, I’d like to hear them.

Is the live-site sitemap actually accurate?

thanks
David Jencks

> On Feb 9, 2020, at 11:55 AM, David Jencks  wrote:
> 
> 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 
>  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//pages/.  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:  

Re: Documentation site

[David Jencks]

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 
 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//pages/.  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 
 
git repos:
tomee  (antora, antora-tomee-7.1.x, 
antora-tomee-7.0.x) Some instructions are in docs/INSTRUCTIONS.adoc
tomee-site-generator  (antora)
tomee-site  (antora)

Thanks!

David Jencks


> On Feb 8, 2020, at 10:32 PM, David Jencks  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.
> 
>