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

[Sean Silva]

Hi Dan, please revert this.

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.


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

-- Sean Silva


>
> Modified:
>     llvm/trunk/docs/Makefile.sphinx
>
> Modified: llvm/trunk/docs/Makefile.sphinx
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/Makefile.sphinx?rev=213661&r1=213660&r2=213661&view=diff
>
> ==============================================================================
> --- llvm/trunk/docs/Makefile.sphinx (original)
> +++ llvm/trunk/docs/Makefile.sphinx Tue Jul 22 10:07:35 2014
> @@ -10,7 +10,7 @@ BUILDDIR      = _build
>  # Internal variables.
>  PAPEROPT_a4     = -D latex_paper_size=a4
>  PAPEROPT_letter = -D latex_paper_size=letter
> -ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER))
> $(SPHINXOPTS) .
> +ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER))
> $(SPHINXOPTS) -W .
>  # the i18n builder cannot share the environment and doctrees with the
> others
>  I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
>
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140722/0aafe005/attachment.html>