<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, Jul 22, 2014 at 11:06 AM, Sean Silva <span dir="ltr"><<a href="mailto:chisophugis@gmail.com" target="_blank">chisophugis@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>Hi Dan, please revert this.<br><br>More comments inline:<br></div><div class="gmail_extra"><br><br>
<div class="gmail_quote"><div class="">On Tue, Jul 22, 2014 at 9:07 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">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></blockquote></div><div><br>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.</div>
</div></div></div></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div class=""><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">

- Having warnings treated as errors will hopefully encourage<br>
  developers to write documentation correctly.<br></blockquote></div><div><br>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.<br>

<br>Good documentation is about good content. Notice how many times <<a href="http://llvm.org/docs/SphinxQuickstartTemplate.html" target="_blank">http://llvm.org/docs/SphinxQuickstartTemplate.html</a>> says to focus on content! Having to worry about markup can only hamper the creation of good content.</div>
</div></div></div></blockquote><div><br></div><div>Sure, but right now it's really easy to unintentionally commit broken markup that most devs could easily fix.</div><div><br></div><div>---</div><div><br></div><div>These concerns aside, I want to make sure that <a href="http://llvm.org">llvm.org</a> 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 <a href="http://llvm.org">llvm.org</a> use this Makefile?  If so, we should revert.</div>
</div></div></div>