This is incredible, and beautiful! Thank you for putting in the work to make this happen!
On Fri, Mar 6, 2020 at 9:06 PM David Jencks <[email protected]> wrote: > Preview at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html < > https://tomee-preview.s3-us-west-2.amazonaws.com/index.html> > > Current state: > > - all content from old source locations on the site (AFAICT, I’ve stopped > looking). This includes all the .md and .mdtext from tomee-site. > - no asciidoc syntax errors > - no internal broken links > - (easy) content deduplication > > There are still some content fixes left to do such as swizzle > elimination. I don’t think these are currently any worse on the preview > than on the live site. > > I think the main remaining questions about the website organization relate > to duplicate and useless or obsolete content. To me, history makes clear > that maintaining the website is difficult for the community and generally > neglected. I think the highest priority should be making it smaller and > better organized so there’s less to maintain and when someone has an > interest in working on it it’s not an insuperable task to figure out how. > > The current preview organization has: > > - content from tomee-site-generator and tomee-site under “common”; there’s > only one version > - content from tomee branches under “tomee” with three versions. Almost > all of this content also appears in “common”; see (1) > - content from the tomee master examples under “examples”, with 3 language > versions. > - the beginnings of embedded JavaDoc, see > https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html > < > https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html > > > > I think the largest remaining questions about the website organization > relate to duplicate and useless or obsolete content. To me, history makes > clear that maintaining the website is difficult for the community and > generally neglected. I think the highest priority should be making it > smaller and better organized so there’s less to maintain and when someone > has an interest in working on it it’s not an insuperable task to figure out > how. > > 1. Previously, except for perhaps a couple of pages, the 8.0, 7.1, and 7.0 > doc branches were identical except for different asciidoc syntax errors. > Now that I’ve brought in the previous .mdtext content from tomee-site git > repo and fixed the syntax errors, there are 4 identical copies. I’ve made > this obvious by eliminating the full text of all but one and using > include:: directives in the other 3. I think much of this content is > somewhere between outdated and wrong, so having 4 identical copies seems > like a less than ideal situation. I think it’s extremely unlikely any of > this content is going to change, although some might be removed. I’d > suggest keeping only the copy in “common” and leaving the versioned > branches for release-specific content, with a pointer to the common docs. > > 2. I haven’t examined the situation in detail, but I think that the > examples are pretty much the same for 7, 7.1, and 8. I don’t think old > examples will ever change, but new ones added. Therefore I suggest having > only one “examples” component with each example saying “since version xxx”. > > 3. There are a lot of pages that are basically empty. Maybe someone had > an idea that documenting something would be a good idea and added an empty > page for it. Since these have been around for many years with no change, I > think it’s time to remove these. > > 4. There are a lot of pages explaining svn, tomcat <= 6, OpenEJB 1 and 3, > etc. Is there any reason to keep these? > > 5. There are several pages with helpful links to peoples people.apache.org > accounts. This is surely not appropriate, and I think all of these are > seriously out of date. Is there any reason to keep these? > > > ——————— > > JavaDoc > > I’ve experimented with javadoc a bit. In my tomee-site antora branch > there’s a small example of using maven to build a java 11 style javadoc jar > from a few bits of stuff pulled into the jbake-built javadoc. This makes > more sense to me than running the javadoc tool every time you want to > preview the website. I also have an experimental Antora plugin that adds > the javadoc to the generated website. There are several ways to do this, > but I like the idea of having the javadoc content inside the Antora page > layout: this is what the preview has. I’m having trouble figuring out how > to make the antora navigation and javadoc search work in this context. > Also, javadoc jars now include some gpl2 licensed scripts, so I’m a bit > unclear as to whether it’s even in line with Apache policy to show > generated javadoc on an apache site. The gpl code doesn’t do much, so I > think it’s plausible to replace it with MIT or apache licensed code. > > I could use some help with: > - constructing a full javadoc jar with maven, having the same source > contents as the jbake javadoc > - figuring out the css and script problems with the embedded javadoc. > This is implausible now, since I haven’t pushed the Antora UI project I’m > using, but I hope to do this soon. If anyone is interested in working on > this I can push them sooner. > > Embedding the javadoc in the site relies on code I’ve written as an Antora > plugin, based on an experimental plugin system I wrote. The idea of a > plugin system is accepted for Antora, but my implementation hasn’t been > even reviewed yet. > > ———— > > In-component organization > > So far I’ve concentrated on finding and fixing content. I think the next > step is to organize the content within the components. The current site > seems to use a jbake attribute to programmatically sort pages. While > relational databases are great for some things, the AS400 file system has > not caught on big time. I’m going to start organizing things by turning > these attributes into topic directories or modules. I expect to organize > at least some of the other “common” docs into topics or modules. Unless I > find a way to easily automate synchronizing the 4 versions of most pages, > I’m going to follow (1) and drop the 3 versioned copies. > > ——————— > > Examples > > Currently my treatment of examples relies on a bash script to copy and > rename the README.adocs. I’m not sure this is fundamentally worse than > what the java code does, it does involve another system. I think it may be > possible to write an Antora plugin to directly gather the example files. I > suspect this plugin may be of general interest since, for example, most of > the camel website is gathered together generated-from-code .adoc files. > > I haven’t looked much at the example READMEs, but many of them seem to > have code copied from the example java files. I’d suggest replacing this > with include:: directives. These can specify line numbers or tags in the > included files, so we can arrange to leave out the Apache notice :-) Since > presumably we want the README to work both in GitHub and in the site, some > magic will be needed to get the include:: to work in both places. > > ————————— > > Site appearance > > I’ve been ignoring site appearance until the basic content and > organization questions are settled. Antora separates the appearance, or > UI, for the site from the content, into a “UI bundle”. At the moment > constructing a custom or modified UI bundle is much more difficult and less > maintainable than it needs to be. I’m planning to prototype a more > flexible system soon. I have a slightly modified default UI bundle for the > javadoc content. If someone wants to help with that I can make it > available now: otherwise I may wait until using it is simpler. > > To see what some Antora sites look like, based on customized UI bundles, > take a look at the links in https://gitlab.com/antora/antora.org/issues/20 > > There’s marginally more customization involved, but > https://blog.yuzutech.fr/blog/ is also nice. > > > David Jencks > > > > > -- Jonathan | [email protected] Pessimists, see a jar as half empty. Optimists, in contrast, see it as half full. Engineers, of course, understand the glass is twice as big as it needs to be.
