[llvm] r213661 - Treat warnings in Sphinx as errors. The reasons for doing this are...

[Dan Liew]

On 22 July 2014 19:06, Sean Silva <chisophugis at gmail.com> wrote:
> Hi Dan, please revert this.

Reverted in r213675

> More comments inline:
>
>
> On Tue, Jul 22, 2014 at 9:07 AM, Dan Liew <dan at su-root.co.uk> wrote:
>>
>> Author: delcypher
>> Date: Tue Jul 22 10:07:35 2014
>> New Revision: 213661
>>
>> URL: http://llvm.org/viewvc/llvm-project?rev=213661&view=rev
>> Log:
>> Treat warnings in Sphinx as errors. The reasons for doing this are...
>>
>> - When CMake builds the documentation with sphinx-build it treats
>>   warnings as errors. We should be consistent with what we do in
>>   CMake.
>
>
> CMake is not the primary way that the Sphinx docs get built. If you want
> these two to be consistent I would suggest that you change CMake to be
> consistent with Makefile.sphinx and not the other way around.

I'm the author of the CMake support for building sphinx documentation
in CMake. When reviewing my patches Reid (CC'ed) preferred warnings to
be treated as errors so that's why building Sphinx documentation in
CMake behaves this way.

@Reid: Would you be happy if I changed this behaviour in CMake so that
warnings are not treated as errors?

>>
>> - Having warnings treated as errors will hopefully encourage
>>   developers to write documentation correctly.
>
>
> This is completely backwards. Good documentation has nothing to do with
> proper markup. Someone with zero knowledge of the thing being documented can
> fix markup errors.
>
> Good documentation is about good content. Notice how many times
> <http://llvm.org/docs/SphinxQuickstartTemplate.html> says to focus on
> content! Having to worry about markup can only hamper the creation of good
> content.

When you put it like that I have to agree with you.

The original reason I made the change was because I was writing
documentation and every time I rebased I frequently had to fix mark up
problems in the docs so I could build the documentation using CMake.
I suppose making warnings errors was a little over zealous, sorry about that.

Thanks,
Dan.