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> > ------------------------------ >
