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

[Dan Liew]

>> @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 think we could experiment with this. We could start with the patch
as it is and if devs find it irritating we could change who gets
notified about documentation build failures (see later on in this
email).

> 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?),

I'm afraid I have very limited data which is only the warnings I've
found and fixed which are...

r214971 - LLD, missing favicon warning (this is a one off).
r214968 - LLD, missing characters in section header
r214967 - Clang, incorrect usage of *
r214076 - LLVM, missing characters in section header
r213559 - LLVM, escape space needed after quoted string (I think
sphinx requiring this is weird)

This probably isn't very much to go on.

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

This is a true. An alternative approach would be to have the buildbot
e-mail a group of developers who agree to fix documentation
warnings/errors as well as the commiter when the sphinx buildbot
fails. Finding such a group may be hard though.