Hi folks. Now that we've gotten the website issues straightened out I looked back at ZOOKEEPER-925 with an eye toward simplifying our mechanics and make it easier for people to generate and maintain the docs.
Given we're using Jekyll/Markdown successfully for the site I tried converting our current documentation (forrest/simpledocbook(xml)) into Markdown using the same tooling I had originally developed for 925. It went pretty smoothly, pretty much looks the same as the forrest generated site, but is much easier to work with: 1) markdown for the source doc format rather than xml 2) jekyll to generate the docs, same as the new site generation I also looked at modernizing and streamlining our process around docs, in particular: 1) src/docs contains the jekyll/markdown based source. Basically the same as before with forrest/sdb but much easier to work with. e.g. consistent with what folks are used to on github. 2) remove /docs from the source repository (git). Committers/contributors no longer need to worry about committing the generated docs into /docs. During active development we'd only be committing src/docs (the markdown) and not /docs (the generated docs). As part of a release we'd still generate a static copy of the docs and include in the release artifact, as well as including on the website. The primary difference here is that the docs on (git) branches would just be the source. Folks could checkout and generate the source docs at any time using jekyll. Note that this is also consistent with many other apache projects. I believe this would be a significant improvement to our current experience around documentation, please take a look at the following branch to get some insight: https://github.com/phunt/zookeeper/tree/jekyll-docs/src/docs Here you can see the original .xml files side-by-side with the markdown formatted docs, in a jekyll based environment. The markdown formatted files having been converted using a variant of the script attached to 925. It's 99% there - still a bit of hand editing necessary to address the corner cases (typically odd/broken formatting in the current doc). You can "jekyll build" same as the site (in src/docs) if you would like to see the generation process itself. If we go ahead with this we'd need to port this to our active branches - 3.4/3.5 and master. (the example branch I linked to is just master). Everyone please take a look and LMK if you have any concerns. Committers please +1 if you agree, comments otw. Regards, Patrick
