<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Aug 6, 2014 at 8:18 AM, Dan Liew <span dir="ltr"><<a href="mailto:dan@su-root.co.uk" target="_blank">dan@su-root.co.uk</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi All,<br>
<br>
Attached is a patch to Zorg that adds<br>
<br>
* A factory for building Sphinx documentation of various LLVM projects<br>
(right now LLVM, Clang and LLD)<br>
<br>
* Three builders (one for each project). They all use the gribozabr4<br>
slave. I could of done a single builder that builds the docs for all<br>
three projects but I figured it would be less noise if people were<br>
notified on a per-project basis of breakages. Although I'm not sure if<br>
I've implemented this correctly.<br>
<br>
Sorry I meant to do this quite a while a go but I've been busy and the<br>
current state of Zorg was a little bit of a barrier.<br>
<br>
The ``getSphinxDocsBuildFactory()`` factory has been tested locally on<br>
my machine but the rest of it is not testable on my machine. This<br>
factory uses the CMake infrastruture for building the sphinx<br>
documentation which currently implies Sphinx warnings are treated as<br>
errors.<br>
<br>
@Sean Silva : I know you disagree with having Sphinx warnings as<br>
errors but I think for the buildbot that this is probably fine.</blockquote><div><br></div><div>Makes sense on a buildbot. I'm still not sure if the noise that a bot might cause for documentation authors will be worth it. Adding a bot like this can result in a qualitatively different experience writing docs, one that could discourage content creation. The "fire and forget" attitude that the current forgiving setup allows is conducive to content creation.</div>
<div><br></div><div>I would prefer if you first got some data on the kinds of issues that creep in, how frequently, how easy are they to fix, and how seriously those issues filter through to affect the final docs (do they result in unreadable formatting or somehow impair/hide the content?), so that we can get a realistic estimate of whether it's worth bothering authors. If it's just a matter of someone (I'll volunteer) setting aside 5 minutes a week to centrally fix minor formatting issues then it's not worth distracting documentation authors.</div>
<div><br></div><div>Remember: this bot does not fix issues. It just exports responsibility for fixing issues to the authors. With code, this makes sense since when things go wrong when bad code is committed, the original author is probably the best equipped for understanding the issue and fixing it. However, with the documentation, I'm not convinced that the original author has any special position w.r.t. understanding the issue and fixing it (the analog to the situation with code issues would be actual content problems, but Sphinx can't warn on those).</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> A<br>
bi-product of me doing this work is I'm probably going to try to<br>
document using the buildbot in the near future because my experience<br>
in getting a build master working locally on my machine was not<br>
particularly pleasant.<br></blockquote><div><br></div><div>Yup, that's how most of the documentation that I've written got written: find something frustrating -> make sure that other people don't have to go through that.</div>
<div><br></div><div>-- Sean Silva</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Thanks,<br>
Dan.<br>
</blockquote></div><br></div></div>