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