You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by David Jencks <da...@gmail.com> on 2020/02/07 04:14:43 UTC
Documentation site
After building myself a couple of tiny websites using Antora (https://antora.org) I’ve become somewhat interested in site generation from asciidoc.
I looked at the current TomEE documentation site and am not entirely thrilled with the appearance.
I spent a couple of hours finding things, arranging the docs into an antora structure, and setting up some configuration.
You can see the results here:
https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
The source for this is at https://github.com/djencks/tomee, antora branch.
This makes no attempt to be a reasonable structure: I just found documentation.adoc, converted it to an Antora nav file, and picked docs.adoc for the home page.
Does this seem like a direction worth pursuing? I’m willing to spend a few days organizing stuff better, fixing the warnings and errors, and sprucing up the UI (I can change colors and remove the irrelevant stuff from the header, but advanced css is beyond me at this point).
There are also a couple of directions of experimentation I might like to pursue:
— Antora doesn’t have a good strategy for multi-language sites. Since there’s at least some translation going on here, this seems like a good place to try out solutions. I haven’t found the translations yet :-) Provisionally my first idea would be to represent languages as versions: 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages. You could pick your language in the lower left component-version selector (on the preview only tomee/8.0 is present)
- I think there might be some javadoc somewhere :-) Antora also doesn’t have a good strategy for including externally generated content. I have an idea around this that just might work :-)
On my GitHub clone I only see a master branch, which I assume is the tomee 8 line. Where are the earlier versions? Where is their documentation? Antora is really good at building sites with many versions of the docs (as long as the source is in asciidoc).
thanks
David Jencks
ps. My google search for the docs brought up this:
https://tomee.apache.org/latest/docs/documentation.html
which doesn’t look good.
Re: Documentation site
Posted by David Jencks <da...@gmail.com>.
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 <da...@gmail.com> 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 <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.jencks@gmail.com <ma...@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>
Re: Documentation site
Posted by David Jencks <da...@gmail.com>.
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 <da...@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>
Re: Documentation site
Posted by David Jencks <da...@gmail.com>.
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.
The preview is still at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>. The other urls have changed slightly (Tomee => tomee).
I think there are still 133 pages on the existing website that I haven’t located source for. If anyone has an idea where they might come from please let me know:
add-my-offering.html http://tomee.apache.org/add-my-offering.html
apache-openejb-3.1.3.html http://tomee.apache.org/download/apache-openejb-3.1.3.html
apache-openejb-3.1.4.html http://tomee.apache.org/download/apache-openejb-3.1.4.html
blogs.html http://tomee.apache.org/blogs.html
buildbot.html http://tomee.apache.org/examples/buildbot.html
contact.html http://tomee.apache.org/misc/contact.html
ejb-+-jpa-+-jsf-+-jax-rs.html http://tomee.apache.org/ejb-+-jpa-+-jsf-+-jax-rs.html
ejb-2.1-compatibility-example.html http://tomee.apache.org/ejb-2.1-compatibility-example.html
ejb-3-annotation-example.html http://tomee.apache.org/ejb-3-annotation-example.html
ejb-3-annotation-examples.html http://tomee.apache.org/ejb-3-annotation-examples.html
ejb-3-example.html http://tomee.apache.org/ejb-3-example.html
ejb-3-examples.html http://tomee.apache.org/ejb-3-examples.html
ejb-3-howto.html http://tomee.apache.org/ejb-3-howto.html
ejb-3-sample-applications.html http://tomee.apache.org/ejb-3-sample-applications.html
ejb-3-sample.html http://tomee.apache.org/ejb-3-sample.html
ejb-3-samples.html http://tomee.apache.org/ejb-3-samples.html
ejb-3-tutorial.html http://tomee.apache.org/ejb-3-tutorial.html
ejb-3-tutorials.html http://tomee.apache.org/ejb-3-tutorials.html
ejb-3.0-specification.html http://tomee.apache.org/ejb-3.0-specification.html
ejb-31-annotation-example.html http://tomee.apache.org/ejb-31-annotation-example.html
ejb-31-annotation-examples.html http://tomee.apache.org/ejb-31-annotation-examples.html
ejb-31-example.html http://tomee.apache.org/ejb-31-example.html
ejb-31-examples.html http://tomee.apache.org/ejb-31-examples.html
ejb-31-howto.html http://tomee.apache.org/ejb-31-howto.html
ejb-31-sample-applications.html http://tomee.apache.org/ejb-31-sample-applications.html
ejb-31-sample.html http://tomee.apache.org/ejb-31-sample.html
ejb-31-samples.html http://tomee.apache.org/ejb-31-samples.html
ejb-31-tutorial.html http://tomee.apache.org/ejb-31-tutorial.html
ejb-31-tutorials.html http://tomee.apache.org/ejb-31-tutorials.html
ejb-annotation-example.html http://tomee.apache.org/ejb-annotation-example.html
ejb-annotation-examples.html http://tomee.apache.org/ejb-annotation-examples.html
ejb-example.html http://tomee.apache.org/ejb-example.html
ejb-glossary.html http://tomee.apache.org/ejb-glossary.html
ejb-howto.html http://tomee.apache.org/ejb-howto.html
ejb-sample-applications.html http://tomee.apache.org/ejb-sample-applications.html
ejb-sample.html http://tomee.apache.org/ejb-sample.html
ejb-samples.html http://tomee.apache.org/ejb-samples.html
ejb-servlet.html http://tomee.apache.org/ejb-servlet.html
ejb-tutorial.html http://tomee.apache.org/ejb-tutorial.html
ejb-tutorials.html http://tomee.apache.org/ejb-tutorials.html
ejb3-annotation-example.html http://tomee.apache.org/ejb3-annotation-example.html
ejb3-annotation-examples.html http://tomee.apache.org/ejb3-annotation-examples.html
ejb3-example.html http://tomee.apache.org/ejb3-example.html
ejb3-examples.html http://tomee.apache.org/ejb3-examples.html
ejb3-howto.html http://tomee.apache.org/ejb3-howto.html
ejb3-sample-applications.html http://tomee.apache.org/ejb3-sample-applications.html
ejb3-sample.html http://tomee.apache.org/ejb3-sample.html
ejb3-samples.html http://tomee.apache.org/ejb3-samples.html
ejb3-tutorial.html http://tomee.apache.org/ejb3-tutorial.html
ejb3-tutorials.html http://tomee.apache.org/ejb3-tutorials.html
example.html http://tomee.apache.org/example.html
examples-table.html http://tomee.apache.org/examples-table.html
faq_openejb-jar.html.html http://tomee.apache.org/faq_openejb-jar.html.html
getting-started-with-eclipse-and-webby.html http://tomee.apache.org/getting-started-with-eclipse-and-webby.html
heritage.html http://tomee.apache.org/misc/heritage.html
index-old.html http://tomee.apache.org/examples/index-old.html
injection-of-datasource-example.html http://tomee.apache.org/injection-of-datasource-example.html
injection-of-entitymanager-example.html http://tomee.apache.org/injection-of-entitymanager-example.html
injection-of-env-entry-example.html http://tomee.apache.org/injection-of-env-entry-example.html
injection-of-other-ejbs-example.html http://tomee.apache.org/injection-of-other-ejbs-example.html
java-ee-6-annotation-example.html http://tomee.apache.org/java-ee-6-annotation-example.html
java-ee-6-annotation-examples.html http://tomee.apache.org/java-ee-6-annotation-examples.html
java-ee-6-example.html http://tomee.apache.org/java-ee-6-example.html
java-ee-6-examples.html http://tomee.apache.org/java-ee-6-examples.html
java-ee-6-howto.html http://tomee.apache.org/java-ee-6-howto.html
java-ee-6-sample-applications.html http://tomee.apache.org/java-ee-6-sample-applications.html
java-ee-6-sample.html http://tomee.apache.org/java-ee-6-sample.html
java-ee-6-samples.html http://tomee.apache.org/java-ee-6-samples.html
java-ee-6-tutorial.html http://tomee.apache.org/java-ee-6-tutorial.html
java-ee-6-tutorials.html http://tomee.apache.org/java-ee-6-tutorials.html
java-ee-annotation-example.html http://tomee.apache.org/java-ee-annotation-example.html
java-ee-annotation-examples.html http://tomee.apache.org/java-ee-annotation-examples.html
java-ee-example.html http://tomee.apache.org/java-ee-example.html
java-ee-examples.html http://tomee.apache.org/java-ee-examples.html
java-ee-howto.html http://tomee.apache.org/java-ee-howto.html
java-ee-sample-applications.html http://tomee.apache.org/java-ee-sample-applications.html
java-ee-sample.html http://tomee.apache.org/java-ee-sample.html
java-ee-samples.html http://tomee.apache.org/java-ee-samples.html
java-ee-tutorial.html http://tomee.apache.org/java-ee-tutorial.html
java-ee-tutorials.html http://tomee.apache.org/java-ee-tutorials.html
javaee-6-annotation-example.html http://tomee.apache.org/javaee-6-annotation-example.html
javaee-6-annotation-examples.html http://tomee.apache.org/javaee-6-annotation-examples.html
javaee-6-example.html http://tomee.apache.org/javaee-6-example.html
javaee-6-examples.html http://tomee.apache.org/javaee-6-examples.html
javaee-6-howto.html http://tomee.apache.org/javaee-6-howto.html
javaee-6-sample-applications.html http://tomee.apache.org/javaee-6-sample-applications.html
javaee-6-sample.html http://tomee.apache.org/javaee-6-sample.html
javaee-6-samples.html http://tomee.apache.org/javaee-6-samples.html
javaee-6-tutorial.html http://tomee.apache.org/javaee-6-tutorial.html
javaee-6-tutorials.html http://tomee.apache.org/javaee-6-tutorials.html
javaee-annotation-example.html http://tomee.apache.org/javaee-annotation-example.html
javaee-annotation-examples.html http://tomee.apache.org/javaee-annotation-examples.html
javaee-example.html http://tomee.apache.org/javaee-example.html
javaee-examples.html http://tomee.apache.org/javaee-examples.html
javaee-howto.html http://tomee.apache.org/javaee-howto.html
javaee-sample-applications.html http://tomee.apache.org/javaee-sample-applications.html
javaee-sample.html http://tomee.apache.org/javaee-sample.html
javaee-samples.html http://tomee.apache.org/javaee-samples.html
javaee-tutorial.html http://tomee.apache.org/javaee-tutorial.html
javaee-tutorials.html http://tomee.apache.org/javaee-tutorials.html
javaee6-annotation-example.html http://tomee.apache.org/javaee6-annotation-example.html
javaee6-annotation-examples.html http://tomee.apache.org/javaee6-annotation-examples.html
javaee6-example.html http://tomee.apache.org/javaee6-example.html
javaee6-examples.html http://tomee.apache.org/javaee6-examples.html
javaee6-howto.html http://tomee.apache.org/javaee6-howto.html
javaee6-sample-applications.html http://tomee.apache.org/javaee6-sample-applications.html
javaee6-sample.html http://tomee.apache.org/javaee6-sample.html
javaee6-samples.html http://tomee.apache.org/javaee6-samples.html
javaee6-tutorial.html http://tomee.apache.org/javaee6-tutorial.html
javaee6-tutorials.html http://tomee.apache.org/javaee6-tutorials.html
legal.html http://tomee.apache.org/misc/legal.html
openejb-0.9.2.html http://tomee.apache.org/download/openejb-0.9.2.html
openejb-1.0-beta-1.html http://tomee.apache.org/download/openejb-1.0-beta-1.html
openejb-1.0-test-matrix.html http://tomee.apache.org/download/openejb-1.0-test-matrix.html
openejb-1.0.html http://tomee.apache.org/download/openejb-1.0.html
openejb-3.0-beta-1.html http://tomee.apache.org/download/openejb-3.0-beta-1.html
openejb-3.0-beta-2.html http://tomee.apache.org/download/openejb-3.0-beta-2.html
openejb-3.0.html http://tomee.apache.org/download/openejb-3.0.html
openejb-3.1.1.html http://tomee.apache.org/download/openejb-3.1.1.html
openejb-3.1.2.html http://tomee.apache.org/download/openejb-3.1.2.html
openejb-3.1.html http://tomee.apache.org/download/openejb-3.1.html
project_info.html http://tomee.apache.org/index.page/project_info.html
simple-stateful-example.html http://tomee.apache.org/simple-stateful-example.html
simple-stateless-example.html http://tomee.apache.org/simple-stateless-example.html
singleton-example.html http://tomee.apache.org/singleton-example.html
testcase-with-testbean-inner-class.html http://tomee.apache.org/testcase-with-testbean-inner-class.html
testing-security-example.html http://tomee.apache.org/testing-security-example.html
testing-transactions-example.html http://tomee.apache.org/testing-transactions-example.html
tomee-1.5.3-snapshot.html http://tomee.apache.org/download/tomee-1.5.3-snapshot.html
tomee-1.6.0-snapshot.html http://tomee.apache.org/download/tomee-1.6.0-snapshot.html
tomee-1.7.x-snapshot.html http://tomee.apache.org/download/tomee-1.7.x-snapshot.html
tomee-7.0.0-snapshot.html http://tomee.apache.org/download/tomee-7.0.0-snapshot.html
whoweare.html http://tomee.apache.org/misc/whoweare.html
I looked in tomee-site-generator master, tomee-master, tomee-7.1.0.x, tomee-7.0.0.x, tomee-1.7.x, and something that might be tomee-1.6.0 although it says it’s a detached head (see other email tonight). I looked for any file with the stem of the html files.
Thanks,
David Jencks
> On Feb 7, 2020, at 11:39 PM, David Jencks <da...@gmail.com> wrote:
>
>
>
>> On Feb 7, 2020, at 3:50 PM, David Blevins <db...@tomitribe.com> wrote:
>>
>>> On Feb 7, 2020, at 2:47 PM, David Jencks <da...@gmail.com> wrote:
>>>
>>> That’s great info and good points!
>>>
>>> To build a site with Antora you basically need to be able to write a little yaml :-)
>>
>> Famous last words :)
>
> Indeed!
>
>
>>
>>> Lets see how far I get with a bit of effort. Is there a way to find all the source for the live CMS (and nothing that’s been replaced)?
>
> Perhaps there are better tools now…. I ran kramdown-asciidoc on the .md files in tomee-site-generator, moved them into antora structure, came up with a nav file that just lists them alphabetically, and now they are another component in the preview. They still need a little sed-based TLC and perhaps even human editing, but they mostly look OK (with a few problems).
>
> Several pages look like someone had a great idea and stopped after writing the title… e.g. azure.adoc. I’m not sure what to do with those.
>
> I haven’t identified the existing navigation to these pages, and I don’t understand yet how it relates to the already-adoc content.
>
> I think my next steps are to clean up the adoc and start to understand the desired organization.
>
> In terms of organization, the existing docs look like there are versions for each 7+ tomee version but I’ve only found the git master branch with I presume the latest.
>
> Anyway, the preview now shows a little bit how Antora can show different versions, although in this case I’m abusing the feature because the content is completely different.
>
> Hints welcome!
>
> David Jencks
>
>>
>> This is now the bulk of what would have to be replaced:
>>
>> - https://github.com/apache/tomee-site-generator
>>
>> The main entry point is here:
>>
>> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/JBake.java#L32
>>
>> The main exit point and integration with the CMS is here:
>>
>> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SvnPub.java#L87
>>
>> That will generate HTML and put it here.
>>
>> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/
>>
>> However, everything that says '.mdtext' is rendered by the CMS and shows up on the internet using our old black and white Twitter bootstrap look and feel. This happens when you go to here and click publish:
>>
>> - https://cms.apache.org/tomee/publish
>>
>> Once that is done there is html generated and sitting an an svn repository somewhere (I can't remember where).
>>
>> Apache will publish sites from git. Ultimately, we need to get to a place where we're doing either Jbake->HTML->Git or Antora->HTML->Git. No SVN or CMS.
>>
>> Almost all of the '.mdtext' files have been committed here:
>>
>> - https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content
>> - https://github.com/apache/tomee-site-generator/blob/master/src/main/jbake/content/comparison.md
>>
>> That page doesn't render by JBake as it's missing the appropriate JBake header, so this CMS page still lives:
>>
>> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/comparison.mdtext
>>
>> Among the complexities is the fact that we're pulling documentation from a few repositories:
>>
>> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Configuration.java#L20
>>
>> We collapse all the source code down to one directory so we can generate one big javadoc tree:
>>
>> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L54
>> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L144
>>
>> There's code to attempt to get a list of contributors, including their pictures:
>>
>> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Contributors.java#L47
>> - http://tomee.apache.org/community/contributors.html
>>
>> That code really needs to be replaced with something that pulls that data from Github because the list of contributors is way way higher:
>>
>> - https://github.com/apache/tomee/graphs/contributors
>>
>>
>> Anyway, at least some pointers.
>>
>> Not entirely sure I answered the question.
>>
>>
>> -David
>>
>
Re: Documentation site
Posted by David Jencks <da...@gmail.com>.
> On Feb 7, 2020, at 3:50 PM, David Blevins <db...@tomitribe.com> wrote:
>
>> On Feb 7, 2020, at 2:47 PM, David Jencks <da...@gmail.com> wrote:
>>
>> That’s great info and good points!
>>
>> To build a site with Antora you basically need to be able to write a little yaml :-)
>
> Famous last words :)
Indeed!
>
>> Lets see how far I get with a bit of effort. Is there a way to find all the source for the live CMS (and nothing that’s been replaced)?
Perhaps there are better tools now…. I ran kramdown-asciidoc on the .md files in tomee-site-generator, moved them into antora structure, came up with a nav file that just lists them alphabetically, and now they are another component in the preview. They still need a little sed-based TLC and perhaps even human editing, but they mostly look OK (with a few problems).
Several pages look like someone had a great idea and stopped after writing the title… e.g. azure.adoc. I’m not sure what to do with those.
I haven’t identified the existing navigation to these pages, and I don’t understand yet how it relates to the already-adoc content.
I think my next steps are to clean up the adoc and start to understand the desired organization.
In terms of organization, the existing docs look like there are versions for each 7+ tomee version but I’ve only found the git master branch with I presume the latest.
Anyway, the preview now shows a little bit how Antora can show different versions, although in this case I’m abusing the feature because the content is completely different.
Hints welcome!
David Jencks
>
> This is now the bulk of what would have to be replaced:
>
> - https://github.com/apache/tomee-site-generator
>
> The main entry point is here:
>
> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/JBake.java#L32
>
> The main exit point and integration with the CMS is here:
>
> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SvnPub.java#L87
>
> That will generate HTML and put it here.
>
> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/
>
> However, everything that says '.mdtext' is rendered by the CMS and shows up on the internet using our old black and white Twitter bootstrap look and feel. This happens when you go to here and click publish:
>
> - https://cms.apache.org/tomee/publish
>
> Once that is done there is html generated and sitting an an svn repository somewhere (I can't remember where).
>
> Apache will publish sites from git. Ultimately, we need to get to a place where we're doing either Jbake->HTML->Git or Antora->HTML->Git. No SVN or CMS.
>
> Almost all of the '.mdtext' files have been committed here:
>
> - https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content
> - https://github.com/apache/tomee-site-generator/blob/master/src/main/jbake/content/comparison.md
>
> That page doesn't render by JBake as it's missing the appropriate JBake header, so this CMS page still lives:
>
> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/comparison.mdtext
>
> Among the complexities is the fact that we're pulling documentation from a few repositories:
>
> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Configuration.java#L20
>
> We collapse all the source code down to one directory so we can generate one big javadoc tree:
>
> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L54
> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L144
>
> There's code to attempt to get a list of contributors, including their pictures:
>
> - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Contributors.java#L47
> - http://tomee.apache.org/community/contributors.html
>
> That code really needs to be replaced with something that pulls that data from Github because the list of contributors is way way higher:
>
> - https://github.com/apache/tomee/graphs/contributors
>
>
> Anyway, at least some pointers.
>
> Not entirely sure I answered the question.
>
>
> -David
>
Re: Documentation site
Posted by David Blevins <db...@tomitribe.com>.
> On Feb 7, 2020, at 2:47 PM, David Jencks <da...@gmail.com> wrote:
>
> That’s great info and good points!
>
> To build a site with Antora you basically need to be able to write a little yaml :-)
Famous last words :)
> Lets see how far I get with a bit of effort. Is there a way to find all the source for the live CMS (and nothing that’s been replaced)?
This is now the bulk of what would have to be replaced:
- https://github.com/apache/tomee-site-generator
The main entry point is here:
- https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/JBake.java#L32
The main exit point and integration with the CMS is here:
- https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SvnPub.java#L87
That will generate HTML and put it here.
- https://svn.apache.org/repos/asf/tomee/site/trunk/content/
However, everything that says '.mdtext' is rendered by the CMS and shows up on the internet using our old black and white Twitter bootstrap look and feel. This happens when you go to here and click publish:
- https://cms.apache.org/tomee/publish
Once that is done there is html generated and sitting an an svn repository somewhere (I can't remember where).
Apache will publish sites from git. Ultimately, we need to get to a place where we're doing either Jbake->HTML->Git or Antora->HTML->Git. No SVN or CMS.
Almost all of the '.mdtext' files have been committed here:
- https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content
- https://github.com/apache/tomee-site-generator/blob/master/src/main/jbake/content/comparison.md
That page doesn't render by JBake as it's missing the appropriate JBake header, so this CMS page still lives:
- https://svn.apache.org/repos/asf/tomee/site/trunk/content/comparison.mdtext
Among the complexities is the fact that we're pulling documentation from a few repositories:
- https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Configuration.java#L20
We collapse all the source code down to one directory so we can generate one big javadoc tree:
- https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L54
- https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L144
There's code to attempt to get a list of contributors, including their pictures:
- https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Contributors.java#L47
- http://tomee.apache.org/community/contributors.html
That code really needs to be replaced with something that pulls that data from Github because the list of contributors is way way higher:
- https://github.com/apache/tomee/graphs/contributors
Anyway, at least some pointers.
Not entirely sure I answered the question.
-David
Re: Documentation site
Posted by David Jencks <da...@gmail.com>.
That’s great info and good points!
To build a site with Antora you basically need to be able to write a little yaml :-)
Lets see how far I get with a bit of effort. Is there a way to find all the source for the live CMS (and nothing that’s been replaced)?
Thanks,
David Jencks
> On Feb 7, 2020, at 2:34 PM, David Blevins <da...@gmail.com> wrote:
>
> Here's the status of the site in general.
>
> The original site was written using the Apache CMS (2011). Several extensions were made to it to get functionality it didn't have. The CMS and the extensions were written in Perl which nobody knows. Much of the extensions were around our examples. Others were to hint css so some pages could leverage twitter bootstrap capabilities. I knew enough to write the extensions, but eventually I became too busy and that left nobody knowing how it all works.
>
> Work on a new site started using JBake (Dec 2016, early 2017). Some custom code was written to replace features of the CMS and extensions. The site went live with around 30% of the content migrated and the rest left as-is, still live and online being served by the CMS. The justification being it was all old content anyway and not worth migrating. It was not deleted either. That left us with two live sites indexed by Google and confused users who couldn't really understand what was current and what was not and why some pages looked different than others. The momentum behind the new site stopped, considering the job done.
>
> Work restarted on the JBake setup (Dec 2018, early 2019) to try and eliminate the CMS further, fix issues with the site, add versioning of content, add support for new languages and publish the Javadoc. We overall went from 30% JBake and 70% CMS to 90% Jbake and 10% CMS. Some of the CMS content, however, still needs significant love. We still have CMS pages indexed on Google that need to be replaced.
>
> So our overall status is we still have live CMS content. Here's one example:
>
> - http://tomee.apache.org/comparison.html
>
> We have some pages that use CMS formatting and therefore don't render and need to be manually addressed:
>
> - https://tomee.apache.org/latest/docs/documentation.html
>
>
>
> My personal perspective is that anything is a good idea as long as there's a person there to make it real. It doesn't matter what technology we use to build the site as much as it matters that there's a person there willing to do the work till it's 100% done.
>
> If someone wants to add a third site building framework on top of the other two, leaving or losing interest before 100% of all content completely converted over. I would probably not be a fan.
>
> If someone wants to completely transition us onto one single system including all content, without exception, leaving no trace of any past site building tech. Sounds good.
>
> Using something non-Java does eliminate most people's ability to help which is what killed the CMS. I have looked at Antora and its features are great and so is Dan. But not being written in Java made it just out of reach for me and I know I would not be able to help at all.
>
> I definitely would not support going live on a third website-building setup with the other two in any way still serving content. Our well-intentioned plans to finish the transitions later have never worked out in practice.
>
> I definitely would *love* to have one fabulous David Jencks active on the project, so despite our past failures I'd support the attempt because getting you active on the project is way bigger than any website. If this is what you're passionate about, then giddy-up. :)
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
>> On Feb 6, 2020, at 8:14 PM, David Jencks <da...@gmail.com> wrote:
>>
>> After building myself a couple of tiny websites using Antora (https://antora.org) I’ve become somewhat interested in site generation from asciidoc.
>>
>> I looked at the current TomEE documentation site and am not entirely thrilled with the appearance.
>>
>> I spent a couple of hours finding things, arranging the docs into an antora structure, and setting up some configuration.
>>
>> You can see the results here:
>>
>> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>>
>> The source for this is at https://github.com/djencks/tomee, antora branch.
>>
>> This makes no attempt to be a reasonable structure: I just found documentation.adoc, converted it to an Antora nav file, and picked docs.adoc for the home page.
>>
>> Does this seem like a direction worth pursuing? I’m willing to spend a few days organizing stuff better, fixing the warnings and errors, and sprucing up the UI (I can change colors and remove the irrelevant stuff from the header, but advanced css is beyond me at this point).
>>
>> There are also a couple of directions of experimentation I might like to pursue:
>>
>> — Antora doesn’t have a good strategy for multi-language sites. Since there’s at least some translation going on here, this seems like a good place to try out solutions. I haven’t found the translations yet :-) Provisionally my first idea would be to represent languages as versions: 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages. You could pick your language in the lower left component-version selector (on the preview only tomee/8.0 is present)
>>
>> - I think there might be some javadoc somewhere :-) Antora also doesn’t have a good strategy for including externally generated content. I have an idea around this that just might work :-)
>>
>> On my GitHub clone I only see a master branch, which I assume is the tomee 8 line. Where are the earlier versions? Where is their documentation? Antora is really good at building sites with many versions of the docs (as long as the source is in asciidoc).
>>
>> thanks
>> David Jencks
>>
>> ps. My google search for the docs brought up this:
>>
>> https://tomee.apache.org/latest/docs/documentation.html
>>
>> which doesn’t look good.
>>
>>
>
Re: Documentation site
Posted by David Blevins <da...@gmail.com>.
Here's the status of the site in general.
The original site was written using the Apache CMS (2011). Several extensions were made to it to get functionality it didn't have. The CMS and the extensions were written in Perl which nobody knows. Much of the extensions were around our examples. Others were to hint css so some pages could leverage twitter bootstrap capabilities. I knew enough to write the extensions, but eventually I became too busy and that left nobody knowing how it all works.
Work on a new site started using JBake (Dec 2016, early 2017). Some custom code was written to replace features of the CMS and extensions. The site went live with around 30% of the content migrated and the rest left as-is, still live and online being served by the CMS. The justification being it was all old content anyway and not worth migrating. It was not deleted either. That left us with two live sites indexed by Google and confused users who couldn't really understand what was current and what was not and why some pages looked different than others. The momentum behind the new site stopped, considering the job done.
Work restarted on the JBake setup (Dec 2018, early 2019) to try and eliminate the CMS further, fix issues with the site, add versioning of content, add support for new languages and publish the Javadoc. We overall went from 30% JBake and 70% CMS to 90% Jbake and 10% CMS. Some of the CMS content, however, still needs significant love. We still have CMS pages indexed on Google that need to be replaced.
So our overall status is we still have live CMS content. Here's one example:
- http://tomee.apache.org/comparison.html
We have some pages that use CMS formatting and therefore don't render and need to be manually addressed:
- https://tomee.apache.org/latest/docs/documentation.html
My personal perspective is that anything is a good idea as long as there's a person there to make it real. It doesn't matter what technology we use to build the site as much as it matters that there's a person there willing to do the work till it's 100% done.
If someone wants to add a third site building framework on top of the other two, leaving or losing interest before 100% of all content completely converted over. I would probably not be a fan.
If someone wants to completely transition us onto one single system including all content, without exception, leaving no trace of any past site building tech. Sounds good.
Using something non-Java does eliminate most people's ability to help which is what killed the CMS. I have looked at Antora and its features are great and so is Dan. But not being written in Java made it just out of reach for me and I know I would not be able to help at all.
I definitely would not support going live on a third website-building setup with the other two in any way still serving content. Our well-intentioned plans to finish the transitions later have never worked out in practice.
I definitely would *love* to have one fabulous David Jencks active on the project, so despite our past failures I'd support the attempt because getting you active on the project is way bigger than any website. If this is what you're passionate about, then giddy-up. :)
--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com
> On Feb 6, 2020, at 8:14 PM, David Jencks <da...@gmail.com> wrote:
>
> After building myself a couple of tiny websites using Antora (https://antora.org) I’ve become somewhat interested in site generation from asciidoc.
>
> I looked at the current TomEE documentation site and am not entirely thrilled with the appearance.
>
> I spent a couple of hours finding things, arranging the docs into an antora structure, and setting up some configuration.
>
> You can see the results here:
>
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>
> The source for this is at https://github.com/djencks/tomee, antora branch.
>
> This makes no attempt to be a reasonable structure: I just found documentation.adoc, converted it to an Antora nav file, and picked docs.adoc for the home page.
>
> Does this seem like a direction worth pursuing? I’m willing to spend a few days organizing stuff better, fixing the warnings and errors, and sprucing up the UI (I can change colors and remove the irrelevant stuff from the header, but advanced css is beyond me at this point).
>
> There are also a couple of directions of experimentation I might like to pursue:
>
> — Antora doesn’t have a good strategy for multi-language sites. Since there’s at least some translation going on here, this seems like a good place to try out solutions. I haven’t found the translations yet :-) Provisionally my first idea would be to represent languages as versions: 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages. You could pick your language in the lower left component-version selector (on the preview only tomee/8.0 is present)
>
> - I think there might be some javadoc somewhere :-) Antora also doesn’t have a good strategy for including externally generated content. I have an idea around this that just might work :-)
>
> On my GitHub clone I only see a master branch, which I assume is the tomee 8 line. Where are the earlier versions? Where is their documentation? Antora is really good at building sites with many versions of the docs (as long as the source is in asciidoc).
>
> thanks
> David Jencks
>
> ps. My google search for the docs brought up this:
>
> https://tomee.apache.org/latest/docs/documentation.html
>
> which doesn’t look good.
>
>
Re: Documentation site
Posted by David Jencks <da...@gmail.com>.
Hi Guillermo,
I’m not yet at the point of thinking about css or even UI changes. If you want to you and you aren’t already familiar with Antora UI bundles you could take a look.
I think the I18n Asciidoc proposal would be too inconvenient for Tomee…. my experience with related systems was pretty horrible. As I understand, Tomee has the (normally english) original adoc file in the same directory as any contributed translations. I think this is going to continue to work well, as it’s really easy to understand what to do…. just take the adoc file and translate it, keeping the structure if appropriate.
I suppose it might be possible to, for each untranslated page and each language, generate a page saying “translate me” and perhaps with a google-translate rendition. That seems a bit in the future though.
I was just thinking about the problems of how to organize and present the translations in Antora.
Thanks!
David Jencks
> On Feb 7, 2020, at 11:16 AM, Guillermo García <bi...@gmail.com> wrote:
>
> On Thu, Feb 6, 2020 at 11:14 PM David Jencks <da...@gmail.com>
> wrote:
>>
>> After building myself a couple of tiny websites using Antora (
> https://antora.org) I’ve become somewhat interested in site generation from
> asciidoc....
>> Does this seem like a direction worth pursuing? I’m willing to spend a
> few days organizing stuff better, fixing the warnings and errors, and
> sprucing up the UI (I can change colors and remove the irrelevant stuff
> from the header, but advanced css is beyond me at this point).
>
> Hi David,
>
> It's a great approach. Count with me in CSS related changes. Just create
> the corresponding JIRA ticket and assign it to my JIRA user: bitcoder.
>
>> There are also a couple of directions of experimentation I might like to
> pursue:
>>
>> — Antora doesn’t have a good strategy for multi-language sites. Since
> there’s at least some translation going on here, this seems like a good
> place to try out solutions. I haven’t found the translations yet :-)
> Provisionally my first idea would be to represent languages as versions:
> 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages. You
> could pick your language in the lower left component-version selector (on
> the preview only tomee/8.0 is present)
>
>
> Not sure how i18n is being provided for TomEE documentation. We could find
> a way to track which parts of a translation need to be updated when the
> source document changes by using a localization management tool, like the
> po4a [1] perl module.
>
> Besides, there's some interesting proposal [2] to use localization in the
> AsciiDoc project coming in next releases.
>
>>
>> ...
>>
>> thanks
>> David Jencks
>>
>> ps. My google search for the docs brought up this:
>>
>> https://tomee.apache.org/latest/docs/documentation.html
>>
>> which doesn’t look good.
>>
>
> It was my first impression too when I was reached the TomEE documentation.
> I already fixed some weird characters for the documentation.adoc in
> TOMEE-2767 [3], I am just waiting for changes to be deployed.
>
> --
> Guillermo Garcia
>
>
> [1] https://github.com/mquinson/po4a
> [2] https://github.com/asciidoctor/asciidoctor/wiki/Design-Doc:-i18n
> [3] https://issues.apache.org/jira/browse/TOMEE-2767
Re: Documentation site
Posted by Guillermo García <bi...@gmail.com>.
On Thu, Feb 6, 2020 at 11:14 PM David Jencks <da...@gmail.com>
wrote:
>
> After building myself a couple of tiny websites using Antora (
https://antora.org) I’ve become somewhat interested in site generation from
asciidoc....
> Does this seem like a direction worth pursuing? I’m willing to spend a
few days organizing stuff better, fixing the warnings and errors, and
sprucing up the UI (I can change colors and remove the irrelevant stuff
from the header, but advanced css is beyond me at this point).
Hi David,
It's a great approach. Count with me in CSS related changes. Just create
the corresponding JIRA ticket and assign it to my JIRA user: bitcoder.
> There are also a couple of directions of experimentation I might like to
pursue:
>
> — Antora doesn’t have a good strategy for multi-language sites. Since
there’s at least some translation going on here, this seems like a good
place to try out solutions. I haven’t found the translations yet :-)
Provisionally my first idea would be to represent languages as versions:
8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages. You
could pick your language in the lower left component-version selector (on
the preview only tomee/8.0 is present)
Not sure how i18n is being provided for TomEE documentation. We could find
a way to track which parts of a translation need to be updated when the
source document changes by using a localization management tool, like the
po4a [1] perl module.
Besides, there's some interesting proposal [2] to use localization in the
AsciiDoc project coming in next releases.
>
> ...
>
> thanks
> David Jencks
>
> ps. My google search for the docs brought up this:
>
> https://tomee.apache.org/latest/docs/documentation.html
>
> which doesn’t look good.
>
It was my first impression too when I was reached the TomEE documentation.
I already fixed some weird characters for the documentation.adoc in
TOMEE-2767 [3], I am just waiting for changes to be deployed.
--
Guillermo Garcia
[1] https://github.com/mquinson/po4a
[2] https://github.com/asciidoctor/asciidoctor/wiki/Design-Doc:-i18n
[3] https://issues.apache.org/jira/browse/TOMEE-2767
Re: Documentation site
Posted by David Jencks <da...@gmail.com>.
Thanks for the pointers!
David
> On Feb 7, 2020, at 1:26 AM, Daniel Dias Dos Santos <da...@gmail.com> wrote:
>
> Hello David,
>
> fantastic your experiment. : )
>
> the translation are in the examples folder:
>
> https://github.com/apache/tomee/tree/master/examples
>
> and about the site of documentation is in address :
>
> https://tomee.apache.org/docs.html
>
> : )
> --
>
> *Daniel Dias dos Santos*
> Java Developer
> SouJava & JCP Member
> GitHub: https://github.com/Daniel-Dos
> Linkedin: www.linkedin.com/in/danieldiasjava
> Twitter: http://twitter.com/danieldiasjava
>
>
> Em sex., 7 de fev. de 2020 às 01:14, David Jencks <da...@gmail.com>
> escreveu:
>
>> After building myself a couple of tiny websites using Antora (
>> https://antora.org) I’ve become somewhat interested in site generation
>> from asciidoc.
>>
>> I looked at the current TomEE documentation site and am not entirely
>> thrilled with the appearance.
>>
>> I spent a couple of hours finding things, arranging the docs into an
>> antora structure, and setting up some configuration.
>>
>> You can see the results here:
>>
>> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <
>> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>>
>> The source for this is at https://github.com/djencks/tomee, antora branch.
>>
>> This makes no attempt to be a reasonable structure: I just found
>> documentation.adoc, converted it to an Antora nav file, and picked
>> docs.adoc for the home page.
>>
>> Does this seem like a direction worth pursuing? I’m willing to spend a
>> few days organizing stuff better, fixing the warnings and errors, and
>> sprucing up the UI (I can change colors and remove the irrelevant stuff
>> from the header, but advanced css is beyond me at this point).
>>
>> There are also a couple of directions of experimentation I might like to
>> pursue:
>>
>> — Antora doesn’t have a good strategy for multi-language sites. Since
>> there’s at least some translation going on here, this seems like a good
>> place to try out solutions. I haven’t found the translations yet :-)
>> Provisionally my first idea would be to represent languages as versions:
>> 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages. You
>> could pick your language in the lower left component-version selector (on
>> the preview only tomee/8.0 is present)
>>
>> - I think there might be some javadoc somewhere :-) Antora also doesn’t
>> have a good strategy for including externally generated content. I have an
>> idea around this that just might work :-)
>>
>> On my GitHub clone I only see a master branch, which I assume is the tomee
>> 8 line. Where are the earlier versions? Where is their documentation?
>> Antora is really good at building sites with many versions of the docs (as
>> long as the source is in asciidoc).
>>
>> thanks
>> David Jencks
>>
>> ps. My google search for the docs brought up this:
>>
>> https://tomee.apache.org/latest/docs/documentation.html
>>
>> which doesn’t look good.
>>
>>
>>
Re: Documentation site
Posted by Daniel Dias Dos Santos <da...@gmail.com>.
Hello David,
fantastic your experiment. : )
the translation are in the examples folder:
https://github.com/apache/tomee/tree/master/examples
and about the site of documentation is in address :
https://tomee.apache.org/docs.html
: )
--
*Daniel Dias dos Santos*
Java Developer
SouJava & JCP Member
GitHub: https://github.com/Daniel-Dos
Linkedin: www.linkedin.com/in/danieldiasjava
Twitter: http://twitter.com/danieldiasjava
Em sex., 7 de fev. de 2020 às 01:14, David Jencks <da...@gmail.com>
escreveu:
> After building myself a couple of tiny websites using Antora (
> https://antora.org) I’ve become somewhat interested in site generation
> from asciidoc.
>
> I looked at the current TomEE documentation site and am not entirely
> thrilled with the appearance.
>
> I spent a couple of hours finding things, arranging the docs into an
> antora structure, and setting up some configuration.
>
> You can see the results here:
>
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>
> The source for this is at https://github.com/djencks/tomee, antora branch.
>
> This makes no attempt to be a reasonable structure: I just found
> documentation.adoc, converted it to an Antora nav file, and picked
> docs.adoc for the home page.
>
> Does this seem like a direction worth pursuing? I’m willing to spend a
> few days organizing stuff better, fixing the warnings and errors, and
> sprucing up the UI (I can change colors and remove the irrelevant stuff
> from the header, but advanced css is beyond me at this point).
>
> There are also a couple of directions of experimentation I might like to
> pursue:
>
> — Antora doesn’t have a good strategy for multi-language sites. Since
> there’s at least some translation going on here, this seems like a good
> place to try out solutions. I haven’t found the translations yet :-)
> Provisionally my first idea would be to represent languages as versions:
> 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages. You
> could pick your language in the lower left component-version selector (on
> the preview only tomee/8.0 is present)
>
> - I think there might be some javadoc somewhere :-) Antora also doesn’t
> have a good strategy for including externally generated content. I have an
> idea around this that just might work :-)
>
> On my GitHub clone I only see a master branch, which I assume is the tomee
> 8 line. Where are the earlier versions? Where is their documentation?
> Antora is really good at building sites with many versions of the docs (as
> long as the source is in asciidoc).
>
> thanks
> David Jencks
>
> ps. My google search for the docs brought up this:
>
> https://tomee.apache.org/latest/docs/documentation.html
>
> which doesn’t look good.
>
>
>