<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, Jul 22, 2014 at 11:26 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"><div class="">On 22 July 2014 19:06, Sean Silva <<a href="mailto:chisophugis@gmail.com">chisophugis@gmail.com</a>> wrote:<br>

> Hi Dan, please revert this.<br>
<br>
</div>Reverted in r213675<br>
<div class=""><br>
> More comments inline:<br>
><br>
><br>
> On Tue, Jul 22, 2014 at 9:07 AM, Dan Liew <<a href="mailto:dan@su-root.co.uk">dan@su-root.co.uk</a>> wrote:<br>
>><br>
>> Author: delcypher<br>
>> Date: Tue Jul 22 10:07:35 2014<br>
>> New Revision: 213661<br>
>><br>
>> URL: <a href="http://llvm.org/viewvc/llvm-project?rev=213661&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=213661&view=rev</a><br>
>> Log:<br>
>> Treat warnings in Sphinx as errors. The reasons for doing this are...<br>
>><br>
>> - When CMake builds the documentation with sphinx-build it treats<br>
>>   warnings as errors. We should be consistent with what we do in<br>
>>   CMake.<br>
><br>
><br>
> CMake is not the primary way that the Sphinx docs get built. If you want<br>
> these two to be consistent I would suggest that you change CMake to be<br>
> consistent with Makefile.sphinx and not the other way around.<br>
<br>
</div>I'm the author of the CMake support for building sphinx documentation<br>
in CMake. When reviewing my patches Reid (CC'ed) preferred warnings to<br>
be treated as errors so that's why building Sphinx documentation in<br>
CMake behaves this way.<br>
<br>
@Reid: Would you be happy if I changed this behaviour in CMake so that<br>
warnings are not treated as errors?</blockquote><div><br></div><div>I'd rather figure something else out.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="">
>><br>
>> - Having warnings treated as errors will hopefully encourage<br>
>>   developers to write documentation correctly.<br>
><br>
><br>
> This is completely backwards. Good documentation has nothing to do with<br>
> proper markup. Someone with zero knowledge of the thing being documented can<br>
> fix markup errors.<br>
><br>
> Good documentation is about good content. Notice how many times<br>
> <<a href="http://llvm.org/docs/SphinxQuickstartTemplate.html" target="_blank">http://llvm.org/docs/SphinxQuickstartTemplate.html</a>> says to focus on<br>
> content! Having to worry about markup can only hamper the creation of good<br>
> content.<br>
<br>
</div>When you put it like that I have to agree with you.<br>
<br>
The original reason I made the change was because I was writing<br>
documentation and every time I rebased I frequently had to fix mark up<br>
problems in the docs so I could build the documentation using CMake.<br>
I suppose making warnings errors was a little over zealous, sorry about that.<br></blockquote><div><br></div><div>The fact that you frequently had to fix markup problems suggests that nobody rebuilds the docs before committing or they ignore the warnings if they do.  I don't want to prevent people from writing docs, but I do want a way to catch broken markup so we can fix it.  We have had bugs filed about broken online docs.</div>
<div><br></div><div>I think the best end state would be:</div><div>- All build systems (CMake and make) default to warnings-as-errors</div><div>- <a href="http://llvm.org">llvm.org</a> builds docs without warnings-as-errors</div>
<div>- Get at least one bot to build the sphinx documentation and send IRC pings</div><div><br></div><div>If nobody has the energy for that, I don't think the status quo is too bad.  If somebody bothers to build with the cmake build system, they'll get the (IMO) intuitive behavior for a build system: the build succeeds if the markup was good.</div>
</div></div></div>