[llvm] r213661 - Treat warnings in Sphinx as errors. The reasons for doing this are...
rnk at google.com
Tue Jul 22 11:38:06 PDT 2014
On Tue, Jul 22, 2014 at 11:26 AM, Dan Liew <dan at su-root.co.uk> wrote:
> 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?
I'd rather figure something else out.
> >> - 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
> > 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
> > 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
The fact that you frequently had to fix markup problems suggests that
nobody rebuilds the docs before committing or they ignore the warnings if
they do. I don't want to prevent people from writing docs, but I do want a
way to catch broken markup so we can fix it. We have had bugs filed about
broken online docs.
I think the best end state would be:
- All build systems (CMake and make) default to warnings-as-errors
- llvm.org builds docs without warnings-as-errors
- Get at least one bot to build the sphinx documentation and send IRC pings
If nobody has the energy for that, I don't think the status quo is too bad.
If somebody bothers to build with the cmake build system, they'll get the
(IMO) intuitive behavior for a build system: the build succeeds if the
markup was good.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the llvm-commits