zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Han <h...@apache.org>
Subject Re: Documentation improvements proposal for ZK
Date Tue, 12 Dec 2017 21:40:04 GMT
+1, this looks great, thanks for doing this Pat!

On Wed, Dec 6, 2017 at 8:45 PM, Patrick Hunt <phunt@apache.org> 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

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