I’d say go for whichever format is most natural for the toolset and maintenance. I’m not tied to Maven site generation either.
On Fri, Sep 18, 2020 at 21:17 Ralph Goers <ralph.go...@dslextreme.com> wrote: > The main web site is built using JBake. Although it is Java based and > still uses Maven the command to build the site is just mvn install > (although it doesn’t actually do an install). All the web pages are either > Markdown or AsciiDoctor. I should also add that you don’t have to use > Maven. You can always just run it from the command line although that > requires installing JBake on your computer. > > > > The documentation for log4cxx is already maintained in its own repo. I > moved it a couple of weeks ago. It is now at > https://github.com/apache/logging-log4cxx-site < > https://github.com/apache/logging-log4cxx-site>. The site could be part > of the main code repo but it would still have to be on a separate asf-site > and asf-staging branch. I rejected doing this because it would mean those > branches contain entirely different content than other branches in the > repo. It also wouldn’t solve the problem of the api docs being separate > because they would be generated from a different branch. > > > > A lot of projects are using Jekyl. I decided not to use it for the main > site as JBake just seemed really easy. > > > > Ralph > > > > > On Sep 18, 2020, at 5:56 PM, Robert Middleton <osfan6...@gmail.com> > wrote: > > > > > > I've been working on smart pointer updates for log4cxx, and as part of > that > > > effort I would also like to improve the documentation to make sure that > it > > > is clear how to use the library. However, this brings up a question as > to > > > how we want to create the website. Currently, the main site is generated > > > using maven, and the API documentation is created with Doxygen. I would > > > like to move away from maven for the site generation, as it means that > the > > > build procedure for the site is weird(utilizing maven and ant). > > > > > > There are three main options that I see: > > > 1. Continue to utilize maven. This has the advantage of making the site > > > consistent with the other log4___ sites. The disadvantage is that it > > > is(currently) weird to update the site and has issues with releases. > > > 2. Move the entire site to doxygen. This would mean that both the main > > > site and the API documentation would be generated at the same time(which > > > would be convenient), but is generally a lot uglier than the maven site. > > > 3. Put the documentation in the log4cxx-site repo and utilize jekyll for > > > the site(see: > > > > https://cwiki.apache.org/confluence/display/INFRA/git+-+.asf.yaml+features#git.asf.yamlfeatures-JekyllCMS > ) > > > This has the advantage of allowing custom skins(like the read-the-docs > > > theme:https://github.com/rundocs/jekyll-rtd-theme), but it means that > the > > > API documentation would still have to be updated manually and comitted > > > separately, and that the site content would live in a separate > > > repository(as far as I can tell the site can't use a subdirectory from > the > > > main repository). > > > > > > Thoughts? > > > > > > -Robert Middleton > > > > -- Matt Sicker <boa...@gmail.com>
