+1, this looks great, thanks for doing this Pat! On Wed, Dec 6, 2017 at 8:45 PM, Patrick Hunt <[email protected]> wrote:
> 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 >
