<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Aug 6, 2014 at 2:47 PM, 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:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="">>> @Sean Silva : I know you disagree with having Sphinx warnings as<br>

>> errors but I think for the buildbot that this is probably fine.<br>
><br>
><br>
> Makes sense on a buildbot. I'm still not sure if the noise that a bot might<br>
> cause for documentation authors will be worth it. Adding a bot like this can<br>
> result in a qualitatively different experience writing docs, one that could<br>
> discourage content creation. The "fire and forget" attitude that the current<br>
> forgiving setup allows is conducive to content creation.<br>
<br>
</div>I think we could experiment with this. We could start with the patch<br>
as it is and if devs find it irritating</blockquote><div><br></div><div>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.</div>
<div><br></div><div>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).</div>
<div><br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"> we could change who gets<br>

notified about documentation build failures (see later on in this<br>
email).<br>
<div class=""><br>
> I would prefer if you first got some data on the kinds of issues that creep<br>
> in, how frequently, how easy are they to fix, and how seriously those issues<br>
> filter through to affect the final docs (do they result in unreadable<br>
> formatting or somehow impair/hide the content?),<br>
<br>
</div>I'm afraid I have very limited data which is only the warnings I've<br>
found and fixed which are...<br>
<br>
r214971 - LLD, missing favicon warning (this is a one off).<br>
r214968 - LLD, missing characters in section header<br>
r214967 - Clang, incorrect usage of *<br>
r214076 - LLVM, missing characters in section header<br>
r213559 - LLVM, escape space needed after quoted string (I think<br>
sphinx requiring this is weird)<br>
<br>
This probably isn't very much to go on.<br></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class=""><br>
> so that we can get a<br>
> realistic estimate of whether it's worth bothering authors. If it's just a<br>
> matter of someone (I'll volunteer) setting aside 5 minutes a week to<br>
> centrally fix minor formatting issues then it's not worth distracting<br>
> documentation authors.<br>
><br>
> Remember: this bot does not fix issues. It just exports responsibility for<br>
> fixing issues to the authors. With code, this makes sense since when things<br>
> go wrong when bad code is committed, the original author is probably the<br>
> best equipped for understanding the issue and fixing it. However, with the<br>
> documentation, I'm not convinced that the original author has any special<br>
> position w.r.t. understanding the issue and fixing it (the analog to the<br>
> situation with code issues would be actual content problems, but Sphinx<br>
> can't warn on those).<br>
<br>
</div>This is a true. An alternative approach would be to have the buildbot<br>
e-mail a group of developers who agree to fix documentation<br>
warnings/errors as well as the commiter when the sphinx buildbot<br>
fails. Finding such a group may be hard though.<br></blockquote><div><br></div><div>Not if the "group" can be a single person.</div><div><br></div><div>-- Sean Silva</div><div> </div></div><br></div></div>