zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tamas Penzes <tam...@cloudera.com>
Subject Re: Documentation improvements proposal for ZK
Date Thu, 07 Dec 2017 21:35:58 GMT
Hi Patrick,

I like the converted documents, much better than the XML solution because
easy to read and easy to edit (from developer point of view).
I have also checked the files one by one with gitprint and found two, which
it cannot display:

https://github.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperAdmin.md
-->
https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperAdmin.md

https://github.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperProgrammers.md
-->
https://gitprint.com/phunt/zookeeper/blob/jekyll-docs/src/docs/zookeeperProgrammers.md

Since they are rendered properly (as far as I see) on github webpage, just
the PDF conversion fails with gitprint I don't know where the problem is.
Still it would be useful if it worked, so anyone with web access could
generate PDFs on-the-fly with the use of gitprint for themselves.

Regards, Tamaas

On Thu, Dec 7, 2017 at 5:45 AM, 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
>



-- 

*Tamás **Pénzes* | Engineering Manager
e. tamaas@cloudera.com
cloudera.com <http://www.cloudera.com/>

[image: Cloudera] <http://www.cloudera.com/>

[image: Cloudera on Twitter] <https://twitter.com/cloudera> [image:
Cloudera on Facebook] <https://www.facebook.com/cloudera> [image: Cloudera
on LinkedIn] <https://www.linkedin.com/company/cloudera>
------------------------------

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