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:36:03 GMT
Not sure if it's a coincidence - but notice that those two .md files are
the largest two markdown files of the set.... Perhaps it's a size issue?

Patrick

On Thu, Dec 7, 2017 at 3:27 PM, Patrick Hunt <phunt@apache.org> wrote:

> 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