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

[Sean Silva]

On Wed, Aug 6, 2014 at 2:47 PM, Dan Liew <dan at su-root.co.uk> wrote:

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


An email from a buildbot is not really an invitation for a dialogue about
whether the dev finds it irritating. Before you set up a bot, I would
recommend that you start out by personally emailing the devs about these
issues. That is an easy way to find out if e.g. they usually need help
understanding what Sphinx is warning about and how to fix it.

Also, unlike a bot, you have a gut feeling about how annoying you are being
when emailing someone about something, which lets you estimate the
"annoyance factor" without having to rely on developers taking action to
inform "the bot operator" that the bot is annoying them (or even worse,
just silently and/or subconsciously contributing less to the documentation).



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

In all these cases, it appears that Sphinx recovers appropriately so that
the content is not compromised. I would be interested to find situations
where Sphinx warns and the content is actually compromised; I can't think
of any off the top of my head.


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

Not if the "group" can be a single person.

-- Sean Silva
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140806/b71d6930/attachment.html>