[docs] Fix all ReST/Sphinx warnings, turn sphinx warnings into errors

Dave Abrahams · Dave Abrahams · commit b1ac7ba7a4b6 · 2013-11-20T23:27:13.000Z
Also revert r10607, which this change obsoletes

Swift SVN r10611
diff --git a/docs/ABI.rst b/docs/ABI.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. _ABI:
 
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -10,17 +10,14 @@ SET(SWIFT_SPHINX_PAPER_SIZE "letter"
   CACHE STRING "Paper size for generated documentation")
 
 SET(SPHINX_ARGS
+  -W
   -D latex_paper_size=${SWIFT_SPHINX_PAPER_SIZE}
   -d ${CMAKE_BINARY_DIR}/doctrees)
 
 if(SPHINX_EXECUTABLE)
   add_custom_target(docs_html ALL
     ${SPHINX_EXECUTABLE} ${SPHINX_ARGS} -b html
-      . ${CMAKE_BINARY_DIR}/docs/html 
-       # filter only stderr; see http://stackoverflow.com/a/15936384/125349
-       # unfortunately I can't get CMake to pass this form through correctly
-       # 2> >(grep -v "\"WARNING: document isn't included in any toctree\"" 1>&2)
-       2>&1 | grep -v "\"WARNING: document isn't included in any toctree\""
+      . ${CMAKE_BINARY_DIR}/docs/html
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
     COMMENT "Building HTML documentation")
 
diff --git a/docs/Expressions.rst b/docs/Expressions.rst
@@ -1,3 +1,5 @@
+:orphan:
+   
 .. @raise litre.TestsAreMissing
 
 ===================
diff --git a/docs/Generics Syntax Tradeoffs.rst b/docs/Generics Syntax Tradeoffs.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 This document summarizes a few email and meeting discussions we have had. Thanks
diff --git a/docs/Import.rst b/docs/Import.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 IMPORT SYNTAX
 =============
 ::
diff --git a/docs/Literals.rst b/docs/Literals.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 Literals
diff --git a/docs/Makefile b/docs/Makefile
@@ -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   = -W -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
diff --git a/docs/Modules.rst b/docs/Modules.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. default-role:: term
 .. title:: Modules User Model
diff --git a/docs/ModulesBuild.rst b/docs/ModulesBuild.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. default-role:: term
 .. title:: Modules Build Model
diff --git a/docs/Objective-C Interoperability.rst b/docs/Objective-C Interoperability.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 ============================
diff --git a/docs/StringDesign.rst b/docs/StringDesign.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 .. raw:: html
diff --git a/docs/TextFormatting.rst b/docs/TextFormatting.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Text Formatting in Swift
 ========================
 
@@ -108,7 +110,7 @@ Output Streams
 ..............
 
 The most fundamental part of this design is ``OutputStream``, a thing
-into which we can stream text: [#character]_
+into which we can stream text: [#character1]_
 
 ::
 
@@ -454,7 +456,7 @@ to tip the balance in favor of the current design.
    generic ``format`` with arguments that depend on the type being
    formatted, so an ad-hoc convention would be just fine.
 
-.. [#character] We don't support streaming individual code points
+.. [#character1] We don't support streaming individual code points
    directly because it's possible to create invalid sequences of code
    points. For any code point that, on its own, represents a valid
    ``Character`` (a.k.a. Unicode `extended grapheme cluster`__), it is
diff --git a/docs/classes.rst b/docs/classes.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 Swift classes in detail
diff --git a/docs/proposals/ClassConstruction.rst b/docs/proposals/ClassConstruction.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================================
  Integrating Swift Constructors with Objective-C
 =================================================
diff --git a/docs/proposals/Clonable.rst b/docs/proposals/Clonable.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 ==========
diff --git a/docs/proposals/Constructors.rst b/docs/proposals/Constructors.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Constructors and Initialization in Swift
 ========================================
 
diff --git a/docs/proposals/Enums.rst b/docs/proposals/Enums.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Swift supports what type theory calls "algebraic data types", or ADTs, which
 are an amalgam of two familiar C-family language features, enums and unions.
 They are similar to enums in that they allow collections of independent symbolic
@@ -51,7 +53,7 @@ C programmers with no interest in learning about ADTs can use 'enum' like they
 always have.
 
 "Union" doesn't exist to Cocoa programmers
----------------------------------------
+------------------------------------------
 
 Cocoa programmers really don't think about unions at all. The frameworks vend
 no public unions. If a Cocoa programmer knows what a union is, it's as a
diff --git a/docs/proposals/Error Handling.rst b/docs/proposals/Error Handling.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. ErrorHandlingModel:
 
diff --git a/docs/proposals/Initialization.rst b/docs/proposals/Initialization.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Initialization
 ==============
 
diff --git a/docs/proposals/Inplace.rst b/docs/proposals/Inplace.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 ==============================================
diff --git a/docs/proposals/KeywordArguments.rst b/docs/proposals/KeywordArguments.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Summary
 -------
 
diff --git a/docs/proposals/Memory and Concurrency Model.rst b/docs/proposals/Memory and Concurrency Model.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. _MemoryAndConcurrencyModel:
 
diff --git a/docs/proposals/MutationModel.rst b/docs/proposals/MutationModel.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. raw:: html
 
    <style>
diff --git a/docs/proposals/OperatorMethods.rst b/docs/proposals/OperatorMethods.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==================
  Operator Methods
 ==================
diff --git a/docs/proposals/OptionSets.rst b/docs/proposals/OptionSets.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 SUMMARY: Option sets should be structs of Bools, with a protocol to provide
 bitwise-ish operations.
 
diff --git a/docs/proposals/ProgramStructureAndCompilationModel.rst b/docs/proposals/ProgramStructureAndCompilationModel.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. _ProgramStructureAndCompilationModel:
 
diff --git a/docs/proposals/TypeState.rst b/docs/proposals/TypeState.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 
 General Type State Notes
diff --git a/docs/proposals/ValueSemantics.rst b/docs/proposals/ValueSemantics.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. _ValueSemantics:
 
diff --git a/docs/proposals/valref.rst b/docs/proposals/valref.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. @raise litre.TestsAreMissing
 .. _valref:
 
diff --git a/docs/weak.rst b/docs/weak.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================
  Weak References
 =================
diff --git a/www/Makefile b/www/Makefile
@@ -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   = -W -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`.. @raise litre.TestsAreMissing`
`2`	`4`	`.. _ABI:`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`IMPORT SYNTAX`
`2`	`4`	`=============`
`3`	`5`	`::`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`=================================================`
`2`	`4`	`Integrating Swift Constructors with Objective-C`
`3`	`5`	`=================================================`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`Constructors and Initialization in Swift`
`2`	`4`	`========================================`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`Initialization`
`2`	`4`	`==============`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`Summary`
`2`	`4`	`-------`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`.. raw:: html`
`2`	`4`
`3`	`5`	`<style>`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`==================`
`2`	`4`	`Operator Methods`
`3`	`5`	`==================`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`SUMMARY: Option sets should be structs of Bools, with a protocol to provide`
`2`	`4`	`bitwise-ish operations.`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`=================`
`2`	`4`	`Weak References`
`3`	`5`	`=================`