Hi Cesar, Thanks for responding! I’ve been so involved with Antora for so long I forget that not everyone is as familiar with it as I :-)
If you haven’t already, taking a look at my preview site might help clarify how Antora deals with components and versions - especially the component selector in the lower left. > On Feb 15, 2020, at 5:45 PM, Cesar Hernandez <cesargu...@gmail.com> wrote: > > Hi David > Thanks for your email and work you are doing. > I have a couple of questions: > >>>>> Combine the remaining pages from tomee-site and tomee-site-generator > into an unversioned component > > Can you expand please a little bit more what are you referring to as the > Unversioned Component? Is this an in-memory process to generate the final > source for Anfora? I really didn’t explain this! Currently the existing web site has some pages at "https://tomee.apache.org/ <https://tomee.apache.org/>“ and some at e.g. "https://tomee.apache.org/tomee-8.0/docs/ <https://tomee.apache.org/tomee-8.0/docs/>“. I’m describing the former as “unversioned” as opposed to the latter which are versioned. In an Antora site, a component is normally versioned (like the “tomee-8.0”, although the URL is going to contain something like “tomee/8.0” instead). However, by picking the special version “master” Antora will leave the version segment out of the url, producing and unversioned component. You can have more versions for that component, but I think that gets confusing. It seems to me that some of the documentation is definitely version-specific and some isn’t. For example, description of the community, how to participate, where git is, etc, aren’t versioned. So I think having an unversioned component is a good idea. I was proposing to start off by putting the content that currently isn’t versioned into it. How this happens isn’t really relevant, but at the moment I’m planning on leaving it in the git repos it is currently in. That’s probably not a good long term solution, but I think it will make it easier to decide what content can be dropped. On the preview site, the “unversioned” content is showing up as tomee version 0.0 and 0.1. I’m going to combine it into a new unversioned component, perhaps “general”. I haven’t found a name I really like :-) > >>>>> * Only have example documentation for 8.0. > Does this mean that current documentation for 7.0 [1] and 7.1 [2] won't be > available anymore in the website? > > In the ticket you mentioned "...Some versions are missing (primarily > examples for 7.1 and 7.0).." > The current TomEE website generator uses the TomEE branches for getting the > examples readme files [3]. > > > [1] https://tomee.apache.org/tomee-7.0/examples/ > [2] https://tomee.apache.org/tomee-7.1/examples/ > [3] https://github.com/apache/tomee/tree/tomee-7.0.x/examples > Having worked for a couple weeks now on this, my opinion is that the biggest problem the tomee site has is too much duplicated outdated useless content. Maintaining the site has IMO not gone well, so reducing its size may be a good idea. Certainly the examples documentation seems to be the best maintained part of the documentation, but I think serious consideration should be given to only showing the examples for the latest version. This is just an idea. If there’s general agreement that the 7.0 and 7.1 examples docs should stay on the site, I’m happy to put them in, although it may be some work as they are still in .md format. I have a pretty good md to adoc translator but checking the results is definitely needed. I’d likely do this in pieces after the other problems are more solved. For one thing, it’s really clear where the examples docs come from, and much of my work has been tracking down the source for much of the site! I hope this clarifies things, and feel free to ask more questions! David Jencks > > > On Sat, Feb 15, 2020 at 01:33 David Jencks <david.a.jen...@gmail.com> wrote: > >> Hi, >> >> I’ve opened some issues (starting at >> https://issues.apache.org/jira/browse/TOMEE-2772 < >> https://issues.apache.org/jira/browse/TOMEE-2772>) about my attempts to >> build a nice TomEE website with Antora. There are quite a few questions I >> still have, and ideally I’ll get some feedback on them soon. However, I’m >> about ready to make unilateral decisions on some of them in order to make >> progress. At this point this is mostly around which content sources and >> which parts of these content sources should be included. >> >> In particular, I plan to: >> >> * Stop looking for the source for the files in svnpubsub not in any source >> I know about >> * Remove the pages from tomee-site that aren’t in svnpubsub >> * Combine the remaining pages from tomee-site and tomee-site-generator >> into an unversioned component >> * Only have example documentation for 8.0. >> >> Thanks >> David Jencks
