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

[Reid Kleckner]

On Tue, Jul 22, 2014 at 11:06 AM, Sean Silva <chisophugis at gmail.com> wrote:

> Hi Dan, please revert this.
>
> 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.
>

Speak for yourself.  Many developers never use make.  Before the CMake
support, I ran sphinx-build manually, rather than reverse engineering the
make-based system.  sphinx-build also works just fine on Windows, while the
make system does not.


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

Sure, but right now it's really easy to unintentionally commit broken
markup that most devs could easily fix.

---

These concerns aside, I want to make sure that llvm.org will
auto-regenerate the docs without warnings-are-errors.  I don't want a
single bit of broken markup to take down all the docs due to a failed
rebuild, or make them all stale.  Does llvm.org use this Makefile?  If so,
we should revert.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140722/caf879ce/attachment.html>