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

[Sean Silva]

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

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

Markup errors have a similar impact on the "end users of the docs" as
benign misspellings (we get bug reports about misspellings too).

Compared to the amount of missing/out-of-date content, these things are
fairly trivial (notice how people have mostly "given up" on reporting bugs
for missing documentation since there's no faith that the bug report will
help; that's a huge issue!).

The purpose of the docs is to help our users and developers understand our
software and use it and improve it. If you really want to make a difference
for the docs, please contribute *content* in one of the following
categories:
- the MI layer
- invariants and structure of Clang's AST
- a "guide for frontend implementors" (especially "approaches and
tradeoffs" for how exploit your language semantics to get the most mileage
out of the optimizer e.g. aliasing, alignment, etc.)
- accurate docs for the debug info format
- a "codebase walkthrough"
- quickstart guides for various pieces of functionality (assemblers,
disassemblers, MCJIT, ...)
- a guide to the useful debugging features of the various LLVM tools
(printing DAG's, CFG's, CG's, etc.) and when to use them
- a "walkthrough of an LLVM module"
- SelectionDAG (and the interaction with relevant TableGen backends)
- ... think of the essential knowledge of LLVM you use everyday, and what
parts of that are missing from the docs ...

These are the things that really make a difference (on the scale of "a
developer gets started with LLVM and goes to become an LLVM developer
devoting a career of full-time work to the project" or "a project becomes
possible thanks to a quick prototype that made use of LLVM" or "saving one
of our developers a bunch of time thanks to teaching them a debugging
feature they didn't know existed" or "a developer becomes able to think
critically about a core piece of the code and suggest and implement
improvements").

Fixing markup does not make very much of a difference.

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