[llvm] r213661 - Treat warnings in Sphinx as errors. The reasons for doing this are...
chisophugis at gmail.com
Tue Jul 22 11:39:08 PDT 2014
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>
>> 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
>>> 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 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
> 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...
More information about the llvm-commits