From 01343bfc98de81ecb9fc60ceb4b1d5a2678d986d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?=
 =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com>
Date: Mon, 17 Sep 2018 16:00:17 +0200
Subject: [PATCH] fix: Sphinx generated incorrect type references for display

When rendering a type reference link, the trailing backtick must be followed by
a non-word character; however the code generated array and union references that
followed this backtick directly with `[` or `)` respectively. This caused a lot
of warnings to be emitted by `sphinx-build`, and resulted in incorrect output.

This adds an escaped space (`\ `) after the backticks, which `sphinx-build`
correctly interprets as a non-word character, but results in no character being
emitted to the output - thus generating the desired output.
---
 packages/jsii-pacmak/lib/targets/sphinx.ts    |  6 ++---
 .../sphinx/_scope_jsii-calc-lib.rst           |  2 +-
 .../expected.jsii-calc/sphinx/jsii-calc.rst   | 26 +++++++++----------
 3 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/packages/jsii-pacmak/lib/targets/sphinx.ts b/packages/jsii-pacmak/lib/targets/sphinx.ts
index 496accc54b..bd23bb04ab 100644
--- a/packages/jsii-pacmak/lib/targets/sphinx.ts
+++ b/packages/jsii-pacmak/lib/targets/sphinx.ts
@@ -523,8 +523,8 @@ class SphinxDocsGenerator extends Generator {
             switch (type.collection.kind) {
                 case spec.CollectionKind.Array:
                     result = {
-                        ref: `${ref}[]`,
-                        display: `${display}[]`
+                        ref: `${ref}\\ []`,
+                        display: `${display}\\ []`
                     };
                     break;
                 case spec.CollectionKind.Map:
@@ -551,7 +551,7 @@ class SphinxDocsGenerator extends Generator {
         // Wrap a string between parenthesis if it contains " or "
         function wrap(str: string): string {
             if (str.indexOf(' or ') === -1) { return str; }
-            return `(${str})`;
+            return `(${str}\\ )`;
         }
     }
 
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-lib/sphinx/_scope_jsii-calc-lib.rst b/packages/jsii-pacmak/test/expected.jsii-calc-lib/sphinx/_scope_jsii-calc-lib.rst
index 7d53fb5c0c..12ba841e69 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc-lib/sphinx/_scope_jsii-calc-lib.rst
+++ b/packages/jsii-pacmak/test/expected.jsii-calc-lib/sphinx/_scope_jsii-calc-lib.rst
@@ -249,7 +249,7 @@ MyFirstStruct (interface)
 
    .. py:attribute:: firstOptional
 
-      :type: string[] or undefined *(abstract)*
+      :type: string\ [] or undefined *(abstract)*
 
 
 Number
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
index 11bf4f7145..cbcfb823f3 100644
--- a/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
+++ b/packages/jsii-pacmak/test/expected.jsii-calc/sphinx/jsii-calc.rst
@@ -348,7 +348,7 @@ AllTypes
 
    .. py:attribute:: anyArrayProperty
 
-      :type: any[]
+      :type: any\ []
 
 
    .. py:attribute:: anyMapProperty
@@ -363,7 +363,7 @@ AllTypes
 
    .. py:attribute:: arrayProperty
 
-      :type: string[]
+      :type: string\ []
 
 
    .. py:attribute:: booleanProperty
@@ -403,7 +403,7 @@ AllTypes
 
    .. py:attribute:: unionArrayProperty
 
-      :type: (number or :py:class:`~jsii-calc.composition.CompositeOperation`)[]
+      :type: (number or :py:class:`~jsii-calc.composition.CompositeOperation`)\ []
 
 
    .. py:attribute:: unionMapProperty
@@ -418,7 +418,7 @@ AllTypes
 
    .. py:attribute:: unknownArrayProperty
 
-      :type: any[]
+      :type: any\ []
 
 
    .. py:attribute:: unknownMapProperty
@@ -754,7 +754,7 @@ Calculator
       A log of all operations.
 
 
-      :type: :py:class:`@scope/jsii-calc-lib.Value`[] *(readonly)*
+      :type: :py:class:`@scope/jsii-calc-lib.Value`\ [] *(readonly)*
 
 
    .. py:attribute:: operationsMap
@@ -762,7 +762,7 @@ Calculator
       A map of per operation name of all operations performed.
 
 
-      :type: string => :py:class:`@scope/jsii-calc-lib.Value`[] *(readonly)*
+      :type: string => :py:class:`@scope/jsii-calc-lib.Value`\ [] *(readonly)*
 
 
    .. py:attribute:: curr
@@ -962,7 +962,7 @@ DerivedStruct (interface)
 
    .. py:attribute:: optionalArray
 
-      :type: string[] or undefined *(abstract)*
+      :type: string\ [] or undefined *(abstract)*
 
 
 DoubleTrouble
@@ -2158,7 +2158,7 @@ ObjectRefsInCollections
 
 
       :param values: 
-      :type values: :py:class:`@scope/jsii-calc-lib.Value`[]
+      :type values: :py:class:`@scope/jsii-calc-lib.Value`\ []
       :rtype: number
 
 
@@ -2601,7 +2601,7 @@ Sum
       The parts to sum.
 
 
-      :type: :py:class:`@scope/jsii-calc-lib.Value`[]
+      :type: :py:class:`@scope/jsii-calc-lib.Value`\ []
 
 
 SyncVirtualMethods
@@ -2981,13 +2981,13 @@ VariadicMethod
    :param \*prefix: a prefix that will be use for all values returned by ``#asArray``.
    :type \*prefix: number
 
-   .. py:method:: asArray(first, *others) -> number[]
+   .. py:method:: asArray(first, *others) -> number\ []
 
       :param first: the first element of the array to be returned (after the ``prefix`` provided at construction time).
       :type first: number
       :param \*others: other elements to be included in the array.
       :type \*others: number
-      :rtype: number[]
+      :rtype: number\ []
 
 
 VirtualMethodPlayground
@@ -3120,7 +3120,7 @@ CompositeOperation
       A set of postfixes to include in a decorated .toString().
 
 
-      :type: string[]
+      :type: string\ []
 
 
    .. py:attribute:: decorationPrefixes
@@ -3128,7 +3128,7 @@ CompositeOperation
       A set of prefixes to include in a decorated .toString().
 
 
-      :type: string[]
+      :type: string\ []
 
 
    .. py:attribute:: stringStyle