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

[Sean Silva]

On Tue, Jul 22, 2014 at 12:26 PM, Reid Kleckner <rnk at google.com> wrote:

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

A long time ago I removed the .bat file equivalent that sphinx-quickstart
produced alongside Makefile.sphinx (the windows situation was obviously
different back then...; I think there may have been another reason). Do you
want it resurrected?

Both Makefile.sphinx and the .bat file are produced by sphinx-quickstart.
They are basically just boilerplate for invoking sphinx-build along with
some niceties like clean. They don't do anything magic and they're just
there because they happen to be what sphinx-quickstart produces.


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

Sphinx produces warnings? I assume that if a developer unintentionally
commits broken markup then that means that they didn't build the docs at
all, so turning warnings into errors would not help.


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

I believe that llvm.org uses Makefile.sphinx . Bill, can you confirm?

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