[docs] Fix syntax highlighting issues to support newer Sphinxes. (#4283)

- Update the Pygments lexer we use for parsing Swift-like code. - State more explicitly which highlighting should be used in which code blocks. - Disable highlighting altogether in certain cases (such as SIL.rst, which has equal amounts grammar and SIL excerpts). This should fix the warnings-as-error issues coming from Sphinx > 1.3.4. Based on a patch by Jeremy Fergason! https://bugs.swift.org/browse/SR-620
apple · Aug 13, 2016 · ca14c36 · ca14c36
1 parent b906a25
commit ca14c36
Show file tree

Hide file tree

Showing 18 changed files with 161 additions and 61 deletions.
diff --git a/docs/ABI.rst b/docs/ABI.rst
@@ -3,6 +3,8 @@
 .. @raise litre.TestsAreMissing
 .. _ABI:
 
+.. highlight:: none
+
 The Swift ABI
 =============
 

diff --git a/docs/ARCOptimization.rst b/docs/ARCOptimization.rst
@@ -1,5 +1,7 @@
 :orphan:
 
+.. highlight:: sil
+
 ==========================
 ARC Optimization for Swift
 ==========================

diff --git a/docs/DebuggingTheCompiler.rst b/docs/DebuggingTheCompiler.rst
@@ -1,5 +1,7 @@
 :orphan:
 
+.. highlight:: none
+
 Debugging the Swift Compiler
 ============================
 

diff --git a/docs/DriverParseableOutput.rst b/docs/DriverParseableOutput.rst
@@ -5,6 +5,8 @@ Parseable Driver Output
 .. contents::
    :local:
 
+.. highlight:: none
+
 Introduction
 ============
 

diff --git a/docs/ErrorHandlingRationale.rst b/docs/ErrorHandlingRationale.rst
@@ -879,15 +879,19 @@ generally needs as much code in the function as implicit manual
 propagation would.  However, we could optimize this for many common
 cases by causing clean-ups to be called automatically by the
 interpretation function.  That is, instead of a landing pad that looks
-notionally like this::
+notionally like this:
 
-  void *exception = ...;
+.. code-block:: objc++
+
+  void *exception = /*...*/;
   SomeCXXType::~SomeCXXType(&foo);
   objc_release(bar);
   objc_release(baz);
   _Unwind_Resume(exception);
 
-The unwind table would have a record that looks notionally like this::
+The unwind table would have a record that looks notionally like this:
+
+.. code-block:: objc++
 
   CALL_WITH_FRAME_ADDRESS(&SomeCXXType::~SomeCXXType, FRAME_OFFSET_OF(foo))
   CALL_WITH_FRAME_VALUE(&objc_release, FRAME_OFFSET_OF(bar))

diff --git a/docs/GitWorkflows.rst b/docs/GitWorkflows.rst
@@ -1,5 +1,7 @@
 :orphan:
 
+.. highlight:: bash
+
 Git Workflows
 =============
 

diff --git a/docs/LibraryEvolution.rst b/docs/LibraryEvolution.rst
@@ -121,7 +121,7 @@ specifying the name of the client library along with the required version::
 
     // Client code
     @available(Magician 1.5)
-    class CrystalBallView : MagicView { … }
+    class CrystalBallView : MagicView { /*…*/ }
 
 Library versions can also be checked dynamically using ``#available``, allowing
 for fallback behavior when the requested library version is not present::
@@ -351,7 +351,7 @@ example using methods::
 
     public struct Point2D {
       var x, y: Double
-      public init(x: Double, y: Double) { … }
+      public init(x: Double, y: Double) { /*…*/ }
     }
 
     extension Point2D {
@@ -368,7 +368,7 @@ polar representation::
 
     public struct Point2D {
       var r, theta: Double
-      public init(x: Double, y: Double) { … }
+      public init(x: Double, y: Double) { /*…*/ }
     }
 
 and the ``x`` and ``y`` properties have now disappeared. To avoid this, the
@@ -693,13 +693,13 @@ can enforce its safe use.
 We've considered two possible syntaxes for this::
 
     @available(1.1)
-    extension Wand : MagicType {…}
+    extension Wand : MagicType {/*…*/}
 
 and
 
 ::
 
-    extension Wand : @available(1.1) MagicType {…}
+    extension Wand : @available(1.1) MagicType {/*…*/}
 
 The former requires fewer changes to the language grammar, but the latter could
 also be used on the declaration of the type itself (i.e. the ``struct``

diff --git a/docs/MutationModel.rst b/docs/MutationModel.rst
@@ -44,7 +44,7 @@ What do we do with this?  Since ``+=`` has an ``inout`` first
 argument, we detect this situation statically (hopefully one day we'll
 have a better error message): 
 
-::
+.. code-block:: swift-console
    
  <REPL Input>:1:9: error: expression does not type-check
  w.title += " (parenthesized remark)"

diff --git a/docs/PatternMatching.rst b/docs/PatternMatching.rst
@@ -292,20 +292,20 @@ braces end up causing a lot of unnecessary vertical whitespace, like so::
 
   switch (x)
   case .foo {
-    …
+    // …
   }
   case .bar {
-    …
+    // …
   }
   
 So instead, let's require the switch statement to have braces, and
 we'll allow the cases to be written without them::
 
   switch (x) {
   case .foo:
-    …
+    // …
   case .bar:
-    …
+    // …
   }
 
 That's really a lot prettier, except it breaks the rule about always grouping

diff --git a/docs/SIL.rst b/docs/SIL.rst
@@ -1,4 +1,5 @@
 .. @raise litre.TestsAreMissing
+.. highlight:: none
 
 Swift Intermediate Language (SIL)
 =================================

diff --git a/docs/StringDesign.rst b/docs/StringDesign.rst
@@ -389,7 +389,9 @@ end, strings support properties for more-specific segmentations:
    `Search Grapheme Cluster: o`
 
 Also, each such segmentation provides a unique ``IndexType``, allowing
-a string to be indexed directly with different indexing schemes::
+a string to be indexed directly with different indexing schemes
+
+.. code-block:: swift-console
 
    |swift| var i = s.searchCharacters.startIndex
    `// r2 : UInt8 = UInt8(83)`

diff --git a/docs/Testing.rst b/docs/Testing.rst
@@ -62,7 +62,9 @@ test suite, via ``utils/build-script --validation-test``.
 Although it is not recommended for day-to-day contributions, it is also
 technically possible to execute the tests directly via CMake. For example, if you have
 built Swift products at the directory ``build/Ninja-ReleaseAssert/swift-macosx-x86_64``,
-you may run the entire test suite directly using the following command::
+you may run the entire test suite directly using the following command:
+
+.. code-block:: bash
 
   cmake --build build/Ninja-ReleaseAssert/swift-macosx-x86_64 -- check-swift-macosx-x86_64
 
@@ -112,7 +114,9 @@ For every target above, there are variants for different optimizations:
   ``executable_test`` in ``-Onone`` mode.
 
 If you need to manually run certain tests, you can invoke LLVM's lit.py script
-directly. For example::
+directly. For example:
+
+.. code-block:: bash
 
     % ${LLVM_SOURCE_ROOT}/utils/lit/lit.py -sv ${SWIFT_BUILD_ROOT}/test-iphonesimulator-i386/Parse/
 
@@ -128,7 +132,7 @@ source 'test/' directory.) There is a more verbose form that specifies the
 testing configuration explicitly, which then allows you to test files
 regardless of location.
 
-::
+.. code-block:: bash
 
     % ${LLVM_SOURCE_ROOT}/utils/lit/lit.py -sv --param swift_site_config=${SWIFT_BUILD_ROOT}/test-iphonesimulator-i386/lit.site.cfg ${SWIFT_SOURCE_ROOT}/test/Parse/
 

diff --git a/docs/archive/LangRefNew.rst b/docs/archive/LangRefNew.rst
@@ -494,7 +494,7 @@ The Swift compiler does not normalize Unicode source code, and matches
 identifiers by code points only.  Source code must be normalized to a consistent
 normalization form before being submitted to the compiler.
 
-::
+.. code-block:: none
 
   // Valid identifiers
   foo

diff --git a/docs/conf.py b/docs/conf.py
@@ -287,6 +287,8 @@
 def swift_get_lexer_by_name(_alias, *args, **kw):
     if _alias == 'swift':
         return swift_pygments_lexers.SwiftLexer()
+    elif _alias == 'sil':
+        return swift_pygments_lexers.SILLexer()
     elif _alias == 'swift-console':
         return swift_pygments_lexers.SwiftConsoleLexer()
     else:

diff --git a/docs/proposals/Concurrency.rst b/docs/proposals/Concurrency.rst
@@ -65,7 +65,9 @@ deallocated class instance.  To understand the bug try to imagine two threads
 executing the SIL code below in lockstep.  After they both load the same value
 they both try to release the object.  One thread succeeds and deallocates the
 object while another thread attempts to read the memory of a deallocated
-object::
+object:
+
+.. code-block:: sil
 
   %10 = global_addr @singleton : $*Bird
 
@@ -78,7 +80,9 @@ object::
 
 Next, we'll look into the problem of sliced values. Intuitively, it is easy to
 see why sharing memory between two threads could lead to catastrophic bugs.
-Consider the program below::
+Consider the program below:
+
+.. code-block:: none
 
   Thread #1:              Thread #2:
    A.first = "John"        A.first = "Paul"

diff --git a/docs/proposals/InoutCOWOptimization.rst b/docs/proposals/InoutCOWOptimization.rst
@@ -1,4 +1,6 @@
 :orphan:
+
+.. highlight:: sil
 
 ================================================
  Copy-On-Write Optimization of ``inout`` Values

diff --git a/docs/proposals/archive/ProgramStructureAndCompilationModel.rst b/docs/proposals/archive/ProgramStructureAndCompilationModel.rst
@@ -3,6 +3,8 @@
 .. @raise litre.TestsAreMissing
 .. _ProgramStructureAndCompilationModel:
 
+.. highlight:: none
+
 Swift Program Structure and Compilation Model
 =============================================