[Zorg][PATCH] Add Sphinx documentation factory and builder for LLVM, Clang and LLD

[Sean Silva]

On Wed, Aug 6, 2014 at 8:18 AM, Dan Liew <dan at su-root.co.uk> wrote:

> Hi All,
>
> Attached is a patch to Zorg that adds
>
> * A factory for building Sphinx documentation of various LLVM projects
> (right now LLVM, Clang and LLD)
>
> * Three builders (one for each project). They all use the gribozabr4
> slave. I could of done a single builder that builds the docs for all
> three projects but I figured it would be less noise if people were
> notified on a per-project basis of breakages. Although I'm not sure if
> I've implemented this correctly.
>
> Sorry I meant to do this quite a while a go but I've been busy and the
> current state of Zorg was a little bit of a barrier.
>
> The ``getSphinxDocsBuildFactory()`` factory has been tested locally on
> my machine but the rest of it is not testable on my machine. This
> factory uses the CMake infrastruture for building the sphinx
> documentation which currently implies Sphinx warnings are treated as
> errors.
>
> @Sean Silva : I know you disagree with having Sphinx warnings as
> errors but I think for the buildbot that this is probably fine.


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.

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.

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


> A
> bi-product of me doing this work is I'm probably going to try to
> document using the buildbot in the near future because my experience
> in getting a build master working locally on my machine was not
> particularly pleasant.
>

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.

-- Sean Silva


>
> Thanks,
> Dan.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140806/9cad7843/attachment.html>