Hi Andi, > On Jul 9, 2021, at 4:13 PM, Andreas Beeker <[email protected]> wrote: > > Hi Dave, > > thanks for the feedback. > > Regarding the different site branch - POI has the site in the bin/src > archives, XmlBeans doesn't. > > Although I'm not a fan of the bin/src archives, as I usually just use a > package manager to get the jars, > I'm a bit undecided what our goal should be: > a) having all in one package and create a snapshot of the docs => include > site in the archive > b) having smaller release archives and create the site by other means => > remove the link to the site (branch)
A simpler way of stating (b) is that we separate the site from the release process. This makes sense to me since since there are portions of the site like download pages that should be changed after the release package has been made. If there are portions of the site that should be versioned with the release and apidocs then we should probably work to include those pages with the apidocs. I vaguely recall that it is possible to extend the apidocs to include other files. > > I'm ok with either generator - jBake or Pelican. If we would go for jBake, I > would recommend to use the groovy-mte templates so the documentation is > really groovy :), i.e. the structure/template is implemented via method calls > or json-like structures. With groovy we can do some interesting approaches to menus to customize by the folder. Here are some jbake/groovy templates I authored starting with the main one: https://github.com/apache/openoffice-org/blob/main/templates/page.gsp <https://github.com/apache/openoffice-org/blob/main/templates/page.gsp> Here are some jbake/groovy templates I contributed to: https://github.com/apache/incubator/blob/master/templates/homepage.gsp <https://github.com/apache/incubator/blob/master/templates/homepage.gsp> https://github.com/apache/incubator/blob/master/templates/projectspage.gsp <https://github.com/apache/incubator/blob/master/templates/projectspage.gsp> > WRT Pelican, I like the ASF and Petri templates most - they rendering is ok > on my hidpi display and smartphone. We worked for that, thanks! > OpenOffice has some scaling problems on the hidpi display - smartphone is ok. I’ll need to refine the OpenOffice Pelican scaling issue. I suspect that the logo is the issue. Did you use a tool? If so, what? I’m fine with either approach. If we go with jBake then we'll need Jenkins jobs. If we go with Pelican then .asf.yaml will fully support us - Infrastructure and I understand the Pelican plugins. > WRT Javadocs, not sure if I understood you right, but I assume we still > generate the docs with the javadoc default layout of the active (= as set in > the environment) JDK and update the POIs minor version directory with it. If > jBake/Pelican complains about a missing link here, we still can use external > links and replace them with local links via gradle for the archives. Sure. One question is whether or not we wish to retain every version of javadocs in the site. > >> Meanwhile others can focus on generating apidocs with Gradle. > The generation of the Javadocs itself is already implemented in gradle - > module-wise and overall - I just need to put the things together for the > src/bin archives. Is the following still accurate: https://svn.apache.org/repos/asf/poi/site/README.txt <https://svn.apache.org/repos/asf/poi/site/README.txt>? It seems to be only partially in gradle since there are instructions here for running "ant javadocs" The published website is here: https://svn.apache.org/repos/asf/poi/site/publish/ <https://svn.apache.org/repos/asf/poi/site/publish/> as I’ve validated here: https://infra-reports.apache.org/site-source/ <https://infra-reports.apache.org/site-source/> For xmlbeans: https://svn.apache.org/repos/asf/xmlbeans/site/ <https://svn.apache.org/repos/asf/xmlbeans/site/> with the published site here: https://svn.apache.org/repos/asf/xmlbeans/site/build/site/ <https://svn.apache.org/repos/asf/xmlbeans/site/build/site/> I can work in parallel with either jBake or Pelican in GitHub producing poi.staged.apache.org <http://poi.staged.apache.org/> and xmlbeans.staged.apache.org <http://xmlbeans.staged.apache.org/> until we are ready to shift. I’ll wait a few days before requesting two git repositories to see if there are other ideas. All the Best, Dave > > Andi. > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] >
