zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Patrick Hunt <ph...@apache.org>
Subject Re: Documentation improvements proposal for ZK
Date Thu, 07 Dec 2017 23:27:26 GMT
That's a very cool service, thanks for the pointer Tamas!

I noticed a link down the bottom to "report issues", however it doesn't
seem like the project is still being maintained, e.g.:
https://github.com/adamburmister/gitprint.com/issues/63

Perhaps you could try running this tool against the page yourself (not
using the service) such that you can get the debugging output? I'm afraid I
don't know where I'd start, the site is giving no information on the
failure. LMK and I'll update the content.

I did run mdl (markdown lint) on the .md files and noticed it highlighted
some issues, Nothing looked particularly serious (e.g. in programmers) and
I haven't gotten around to cleaning those up given I haven't moved over to
that phase yet (still tweaking the conversion script).

Thanks!

Patrick


On Thu, Dec 7, 2017 at 1:35 PM, Tamas Penzes <tamaas@cloudera.com> wrote:

> 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