zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Patrick Hunt <ph...@apache.org>
Subject Documentation improvements proposal for ZK
Date Thu, 07 Dec 2017 04:45:52 GMT
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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message