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

[Reid Kleckner]

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

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...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140722/8da88203/attachment.html>