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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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. [email protected] >> 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> >> ------------------------------ >> > >
