<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Jul 22, 2014 at 12:38 PM, Reid Kleckner <span dir="ltr"><<a href="mailto:rnk@google.com" target="_blank">rnk@google.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div class="">On Tue, Jul 22, 2014 at 11:26 AM, Dan Liew <span dir="ltr"><<a href="mailto:dan@su-root.co.uk" target="_blank">dan@su-root.co.uk</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div>On 22 July 2014 19:06, Sean Silva <<a href="mailto:chisophugis@gmail.com" target="_blank">chisophugis@gmail.com</a>> wrote:<br>


> Hi Dan, please revert this.<br>
<br>
</div>Reverted in r213675<br>
<div><br>
> More comments inline:<br>
><br>
><br>
> On Tue, Jul 22, 2014 at 9:07 AM, Dan Liew <<a href="mailto:dan@su-root.co.uk" target="_blank">dan@su-root.co.uk</a>> wrote:<br>
>><br>
>> Author: delcypher<br>
>> Date: Tue Jul 22 10:07:35 2014<br>
>> New Revision: 213661<br>
>><br>
>> URL: <a href="http://llvm.org/viewvc/llvm-project?rev=213661&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=213661&view=rev</a><br>
>> Log:<br>
>> Treat warnings in Sphinx as errors. The reasons for doing this are...<br>
>><br>
>> - When CMake builds the documentation with sphinx-build it treats<br>
>>   warnings as errors. We should be consistent with what we do in<br>
>>   CMake.<br>
><br>
><br>
> CMake is not the primary way that the Sphinx docs get built. If you want<br>
> these two to be consistent I would suggest that you change CMake to be<br>
> consistent with Makefile.sphinx and not the other way around.<br>
<br>
</div>I'm the author of the CMake support for building sphinx documentation<br>
in CMake. When reviewing my patches Reid (CC'ed) preferred warnings to<br>
be treated as errors so that's why building Sphinx documentation in<br>
CMake behaves this way.<br>
<br>
@Reid: Would you be happy if I changed this behaviour in CMake so that<br>
warnings are not treated as errors?</blockquote><div><br></div></div><div>I'd rather figure something else out.</div><div class=""><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">

<div>
>><br>
>> - Having warnings treated as errors will hopefully encourage<br>
>>   developers to write documentation correctly.<br>
><br>
><br>
> This is completely backwards. Good documentation has nothing to do with<br>
> proper markup. Someone with zero knowledge of the thing being documented can<br>
> fix markup errors.<br>
><br>
> Good documentation is about good content. Notice how many times<br>
> <<a href="http://llvm.org/docs/SphinxQuickstartTemplate.html" target="_blank">http://llvm.org/docs/SphinxQuickstartTemplate.html</a>> says to focus on<br>
> content! Having to worry about markup can only hamper the creation of good<br>
> content.<br>
<br>
</div>When you put it like that I have to agree with you.<br>
<br>
The original reason I made the change was because I was writing<br>
documentation and every time I rebased I frequently had to fix mark up<br>
problems in the docs so I could build the documentation using CMake.<br>
I suppose making warnings errors was a little over zealous, sorry about that.<br></blockquote><div><br></div></div><div>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.</div>

<div><br></div><div>I think the best end state would be:</div><div>- All build systems (CMake and make) default to warnings-as-errors</div><div>- <a href="http://llvm.org" target="_blank">llvm.org</a> builds docs without warnings-as-errors</div>

<div>- Get at least one bot to build the sphinx documentation and send IRC pings</div><div><br></div><div>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.</div>
</div></div></div></blockquote><div><br></div><div>Markup errors have a similar impact on the "end users of the docs" as benign misspellings (we get bug reports about misspellings too).<br><br>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!).<br>
</div><div><br>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:<br>
</div><div>- the MI layer<br>- invariants and structure of Clang's AST<br>- 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.)<br>
- accurate docs for the debug info format<br></div><div>- a "codebase walkthrough"<br>- quickstart guides for various pieces of functionality (assemblers, disassemblers, MCJIT, ...)<br></div><div>- 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<br>
</div><div>- a "walkthrough of an LLVM module"<br></div><div>- SelectionDAG (and the interaction with relevant TableGen backends)<br></div><div>- ... think of the essential knowledge of LLVM you use everyday, and what parts of that are missing from the docs ...<br>
</div><div><br>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").<br>
<br>Fixing markup does not make very much of a difference.</div><div><br></div><div>-- Sean Silva<br></div></div><br></div></div>