Any other comments? I haven't seen any negative feedback so I'm going to move ahead with this unless someone speaks up soon. :-)
Regards, Patrick On Tue, Dec 12, 2017 at 1:40 PM, Michael Han <[email protected]> wrote: > +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 > > >
