From 31c34c9538b0ce8304b3cdfa5e07720b2dfb101c Mon Sep 17 00:00:00 2001
From: Justin Van Patten <jvp@justinvp.com>
Date: Thu, 27 Jun 2019 09:41:17 -0700
Subject: [PATCH 1/4] Update API doc styling for Python

Bring back the styles used for our Python API docs, convert to use Tailwind, and make further tweaks to make it look even better. For example, all definitions now look like code blocks and indentation and spacing is used to improve the hierarchy of the content.
---
 assets/sass/_api-python.scss | 119 +++++++++++++++++++++++++++++++++++
 assets/sass/styles.scss      |   1 +
 2 files changed, 120 insertions(+)
 create mode 100644 assets/sass/_api-python.scss

diff --git a/assets/sass/_api-python.scss b/assets/sass/_api-python.scss
new file mode 100644
index 000000000000..5377a2208a24
--- /dev/null
+++ b/assets/sass/_api-python.scss
@@ -0,0 +1,119 @@
+//
+// Styling for Python documentation
+//
+
+// Our Python documentation is generated by the Sphinx HTML generator. We use it
+// to generate unstyled HTML that we inject directly into our web page. Naturally,
+// we want to style it a bit to make it not look terrible.
+//
+// Our style selectors are split into two toplevel selectors: a div starting with "module-",
+// and a div with class "section" whose ID begins with "pulumi". These two things identify
+// the two kinds of pages that Sphinx emits: the first kind is a module page, containing
+// information on on members within a module, and the second kind is a table of contents.
+
+// Use the same icon that AnchorJS uses for anchor links.
+$anchorjs-font: 1em/1 anchorjs-icons;
+$anchorjs-content: "\e9cb";
+
+// This selector is for the table of contents. There's not much on this page except for a bunch of links.
+div.section[id^="pulumi"] {
+    a.headerlink {
+        @apply invisible;
+    }
+}
+
+// This selector is for the module page and for the Pulumi Python SDK page.
+div[id^="module-"], div[id="pulumi-python-sdk"] {
+    // Don't show the header link - there's an anchorjs link on this header that does the
+    // job just as well.
+    h1[id$="\B6"],
+    h2[id$="\B6"] {
+        a.headerlink {
+            @apply hidden;
+        }
+    }
+
+    // Add some margin to the top of sections.
+    div.section {
+        @apply mt-8;
+    }
+
+    // Add some margin above and below parameter tables.
+    dd {
+        > table {
+            @apply my-4;
+        }
+    }
+
+    // The definition of a single (Python) class or function. Not to be confused with the CSS class.
+    // Sphinx emits a DL for every class it processes, with a few well-known immediate
+    // subchildren:
+    dl.class, dl.function, dl.exception {
+        > dt {
+            // Top-level definitions get larger text.
+            @apply text-lg;
+
+            // Hide the header link when not hovering.
+            > a.headerlink {
+                @apply invisible;
+            }
+        }
+
+        dt {
+            // Use the same styling as our `pre` tags for definitions.
+            @apply bg-gray-100 py-4 px-5 rounded border border-gray-200 scrolling-auto overflow-scroll my-4 leading-normal;
+
+            // Remove italics in these definitions.
+            em {
+                @apply not-italic;
+            }
+
+            code {
+                // Various code blocks are placed next to each other. In these cases, we don't want
+                // any padding between them, and want a consistent font size with surrounding text.
+                @apply p-0;
+                font-size: 100%;
+
+                // descname identifies the name of the thing. This is what users come for, so bold it.
+                &.descname {
+                    @apply font-bold;
+                }
+            }
+        }
+
+        // Add some margin to the left to indent the content under definitions.
+        dd {
+            @apply ml-8;
+        }
+
+        // Show the headerlink when hovering over the class or function definition,
+        // but use the AnchorJS icon.
+        > dt:hover > a.headerlink {
+            &:after {
+                @apply visible;
+                font: $anchorjs-font;
+                content: $anchorjs-content;
+            }
+        }
+
+        // The body of the class's documentation is in a dd.
+        > dd {
+            // Add some padding underneath the class documentation to help separate sections of the document.
+            @apply pb-8;
+
+            // Like the definition, only show the headerlink if the user is hovering over the entity,
+            // and use the AnchorJS icon.
+            > dl dt a.headerlink {
+                @apply invisible;
+            }
+
+            > dl dt:hover a.headerlink {
+                &:after {
+                    @apply visible;
+                    font: $anchorjs-font;
+                    content: $anchorjs-content;
+                }
+            }
+        }
+    }
+}
diff --git a/assets/sass/styles.scss b/assets/sass/styles.scss
index 88e9afd15bfb..f7aab3f22b00 100644
--- a/assets/sass/styles.scss
+++ b/assets/sass/styles.scss
@@ -5,6 +5,7 @@
 @import "mixins";
 
 @import "animation";
+@import "api-python";
 @import "buttons";
 @import "code";
 @import "fonts";

From f1d871684574c658f2a9cf4232fec6136659b8f8 Mon Sep 17 00:00:00 2001
From: Justin Van Patten <jvp@justinvp.com>
Date: Thu, 27 Jun 2019 09:42:39 -0700
Subject: [PATCH 2/4] Only emit the <h1>.Title</h1> if there is a .Title

The generated Python API docs don't currently include front matter and therefore do not have a title. We should fix the Python docs gen to do that, but in the meantime, only emit `<h1>.Title</h1>` if the page has a `.Title`, to avoid an unnecessary gap at the top of the page.
---
 layouts/docs/list.html | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/layouts/docs/list.html b/layouts/docs/list.html
index 126ee2648a98..20380be4cb55 100644
--- a/layouts/docs/list.html
+++ b/layouts/docs/list.html
@@ -17,7 +17,10 @@
             </div>
 
             <div class="md:w-7/12">
-                <h1>{{ .Title }}</h1>
+                {{ if ne .Title "" }}
+                    <h1>{{ .Title }}</h1>
+                {{ end }}
+
                 {{ .Content }}
             </div>
         </div>

From 63fcebba0efbf66e5a87ba47a9b7f8689d772d80 Mon Sep 17 00:00:00 2001
From: Justin Van Patten <jvp@justinvp.com>
Date: Thu, 27 Jun 2019 13:11:57 -0700
Subject: [PATCH 3/4] Update API doc styling for Node.js

---
 assets/sass/_api-nodejs.scss | 50 ++++++++++++++++++++++++++++++++++++
 assets/sass/styles.scss      |  1 +
 2 files changed, 51 insertions(+)
 create mode 100644 assets/sass/_api-nodejs.scss

diff --git a/assets/sass/_api-nodejs.scss b/assets/sass/_api-nodejs.scss
new file mode 100644
index 000000000000..76734f86fae8
--- /dev/null
+++ b/assets/sass/_api-nodejs.scss
@@ -0,0 +1,50 @@
+// Add some styling to the Index/Module sections.
+.pdoc-module-header.toggleButton + .pdoc-module-contents {
+    // Add some margin at the bottom, so it's not so close to the list of .ts files.
+    ul {
+        @apply mb-8;
+    }
+
+    // We want these links to look like normal content links.
+    a {
+        @apply text-blue-600;
+
+        &:hover {
+            @apply text-blue-700;
+        }
+    }
+}
+
+.pdoc-module-header {
+    @apply text-xl;
+
+    // Make the module header match the same as code blocks.
+    @apply bg-gray-100 py-4 px-5 rounded border border-gray-200 my-4 leading-normal;
+
+    // Remove the left margin and color used for toggle buttons in the TOC.
+    &.toggleButton {
+        @apply ml-0;
+        color: inherit;
+    }
+}
+
+.pdoc-member-header {
+    @apply text-lg;
+}
+
+.pdoc-module-contents,
+.pdoc-member-contents {
+    // Add some indentation to make it easier to visually see the hierarchy of the content.
+    @apply ml-4;
+
+    // We want visually recognizable links here.
+    .highlight {
+        a {
+            @apply text-blue-600;
+
+            &:hover {
+                @apply text-blue-700;
+            }
+        }
+    }
+}
diff --git a/assets/sass/styles.scss b/assets/sass/styles.scss
index f7aab3f22b00..721f325e264a 100644
--- a/assets/sass/styles.scss
+++ b/assets/sass/styles.scss
@@ -5,6 +5,7 @@
 @import "mixins";
 
 @import "animation";
+@import "api-nodejs";
 @import "api-python";
 @import "buttons";
 @import "code";

From feb180f72b9ca0a6b8484f8d6746d9f593195a62 Mon Sep 17 00:00:00 2001
From: Justin Van Patten <jvp@justinvp.com>
Date: Thu, 27 Jun 2019 11:43:10 -0700
Subject: [PATCH 4/4] Update _pygments.scss to select .highlight instead of
 .chroma

The syntax highlighted code generated by Hugo looks like:

```
<div class="highlight">
    <pre class="chroma">
        <code class="language-foo">
        ...
        </code>
    </pre>
</div>
```

And our styles looks like:

```
.chroma .k { ... }
.chroma .kc { ... }
...
```

This works good, but our generated Python docs, which uses Pygments to do the syntax highlighting, doesn't use `.chroma`, so it doesn't get any syntax highlighting currently, even though all the Pygments classes are there.

This is true for our Node.js docs as well, although, based on how we generate the code for that currently, we could relatively easily update the templates to include a `.chroma` class.

In all cases, the code that we want highlighted will have a `.highlight` class surrounding it, so just update our styles to select `.highlight` instead of `.chroma`.

```
.highlight .k { ... }
.highlight .kc { ... }
...
```
---
 assets/sass/_pygments.scss | 160 ++++++++++++++++++-------------------
 1 file changed, 80 insertions(+), 80 deletions(-)

diff --git a/assets/sass/_pygments.scss b/assets/sass/_pygments.scss
index 5b151c1cbff5..6a4732dcd0b9 100644
--- a/assets/sass/_pygments.scss
+++ b/assets/sass/_pygments.scss
@@ -11,73 +11,73 @@
     Light mode (the default) uses the "friendly" theme.
  */
 
-/* Error */ .chroma .err {  }
-/* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
-/* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
-/* LineHighlight */ .chroma .hl { display: block; width: 100%;background-color: #ffffcc }
-/* LineNumbersTable */ .chroma .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
-/* LineNumbers */ .chroma .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
-/* Keyword */ .chroma .k { color: #007020; font-weight: bold }
-/* KeywordConstant */ .chroma .kc { color: #007020; font-weight: bold }
-/* KeywordDeclaration */ .chroma .kd { color: #007020; font-weight: bold }
-/* KeywordNamespace */ .chroma .kn { color: #007020; font-weight: bold }
-/* KeywordPseudo */ .chroma .kp { color: #007020 }
-/* KeywordReserved */ .chroma .kr { color: #007020; font-weight: bold }
-/* KeywordType */ .chroma .kt { color: #902000 }
-/* NameAttribute */ .chroma .na { color: #4070a0 }
-/* NameBuiltin */ .chroma .nb { color: #007020 }
-/* NameClass */ .chroma .nc { color: #0e84b5; font-weight: bold }
-/* NameConstant */ .chroma .no { color: #60add5 }
-/* NameDecorator */ .chroma .nd { color: #555555; font-weight: bold }
-/* NameEntity */ .chroma .ni { color: #d55537; font-weight: bold }
-/* NameException */ .chroma .ne { color: #007020 }
-/* NameFunction */ .chroma .nf { color: #06287e }
-/* NameLabel */ .chroma .nl { color: #002070; font-weight: bold }
-/* NameNamespace */ .chroma .nn { color: #0e84b5; font-weight: bold }
-/* NameTag */ .chroma .nt { color: #062873; font-weight: bold }
-/* NameVariable */ .chroma .nv { color: #bb60d5 }
-/* LiteralString */ .chroma .s { color: #4070a0 }
-/* LiteralStringAffix */ .chroma .sa { color: #4070a0 }
-/* LiteralStringBacktick */ .chroma .sb { color: #4070a0 }
-/* LiteralStringChar */ .chroma .sc { color: #4070a0 }
-/* LiteralStringDelimiter */ .chroma .dl { color: #4070a0 }
-/* LiteralStringDoc */ .chroma .sd { color: #4070a0; font-style: italic }
-/* LiteralStringDouble */ .chroma .s2 { color: #4070a0 }
-/* LiteralStringEscape */ .chroma .se { color: #4070a0; font-weight: bold }
-/* LiteralStringHeredoc */ .chroma .sh { color: #4070a0 }
-/* LiteralStringInterpol */ .chroma .si { color: #70a0d0; font-style: italic }
-/* LiteralStringOther */ .chroma .sx { color: #c65d09 }
-/* LiteralStringRegex */ .chroma .sr { color: #235388 }
-/* LiteralStringSingle */ .chroma .s1 { color: #4070a0 }
-/* LiteralStringSymbol */ .chroma .ss { color: #517918 }
-/* LiteralNumber */ .chroma .m { color: #40a070 }
-/* LiteralNumberBin */ .chroma .mb { color: #40a070 }
-/* LiteralNumberFloat */ .chroma .mf { color: #40a070 }
-/* LiteralNumberHex */ .chroma .mh { color: #40a070 }
-/* LiteralNumberInteger */ .chroma .mi { color: #40a070 }
-/* LiteralNumberIntegerLong */ .chroma .il { color: #40a070 }
-/* LiteralNumberOct */ .chroma .mo { color: #40a070 }
-/* Operator */ .chroma .o { color: #666666 }
-/* OperatorWord */ .chroma .ow { color: #007020; font-weight: bold }
-/* Comment */ .chroma .c { color: #60a0b0; font-style: italic }
-/* CommentHashbang */ .chroma .ch { color: #60a0b0; font-style: italic }
-/* CommentMultiline */ .chroma .cm { color: #60a0b0; font-style: italic }
-/* CommentSingle */ .chroma .c1 { color: #60a0b0; font-style: italic }
-/* CommentSpecial */ .chroma .cs { color: #60a0b0; background-color: #fff0f0 }
-/* CommentPreproc */ .chroma .cp { color: #007020 }
-/* CommentPreprocFile */ .chroma .cpf { color: #007020 }
-/* GenericDeleted */ .chroma .gd { color: #a00000 }
-/* GenericEmph */ .chroma .ge { font-style: italic }
-/* GenericError */ .chroma .gr { color: #ff0000 }
-/* GenericHeading */ .chroma .gh { color: #000080; font-weight: bold }
-/* GenericInserted */ .chroma .gi { color: #00a000 }
-/* GenericOutput */ .chroma .go { color: #888888 }
-/* GenericPrompt */ .chroma .gp { color: #c65d09; font-weight: bold }
-/* GenericStrong */ .chroma .gs { font-weight: bold }
-/* GenericSubheading */ .chroma .gu { color: #800080; font-weight: bold }
-/* GenericTraceback */ .chroma .gt { color: #0044dd }
-/* GenericUnderline */ .chroma .gl { text-decoration: underline }
-/* TextWhitespace */ .chroma .w { color: #bbbbbb }
+/* Error */ .highlight .err {  }
+/* LineTableTD */ .highlight .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
+/* LineTable */ .highlight .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
+/* LineHighlight */ .highlight .hl { display: block; width: 100%;background-color: #ffffcc }
+/* LineNumbersTable */ .highlight .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
+/* LineNumbers */ .highlight .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
+/* Keyword */ .highlight .k { color: #007020; font-weight: bold }
+/* KeywordConstant */ .highlight .kc { color: #007020; font-weight: bold }
+/* KeywordDeclaration */ .highlight .kd { color: #007020; font-weight: bold }
+/* KeywordNamespace */ .highlight .kn { color: #007020; font-weight: bold }
+/* KeywordPseudo */ .highlight .kp { color: #007020 }
+/* KeywordReserved */ .highlight .kr { color: #007020; font-weight: bold }
+/* KeywordType */ .highlight .kt { color: #902000 }
+/* NameAttribute */ .highlight .na { color: #4070a0 }
+/* NameBuiltin */ .highlight .nb { color: #007020 }
+/* NameClass */ .highlight .nc { color: #0e84b5; font-weight: bold }
+/* NameConstant */ .highlight .no { color: #60add5 }
+/* NameDecorator */ .highlight .nd { color: #555555; font-weight: bold }
+/* NameEntity */ .highlight .ni { color: #d55537; font-weight: bold }
+/* NameException */ .highlight .ne { color: #007020 }
+/* NameFunction */ .highlight .nf { color: #06287e }
+/* NameLabel */ .highlight .nl { color: #002070; font-weight: bold }
+/* NameNamespace */ .highlight .nn { color: #0e84b5; font-weight: bold }
+/* NameTag */ .highlight .nt { color: #062873; font-weight: bold }
+/* NameVariable */ .highlight .nv { color: #bb60d5 }
+/* LiteralString */ .highlight .s { color: #4070a0 }
+/* LiteralStringAffix */ .highlight .sa { color: #4070a0 }
+/* LiteralStringBacktick */ .highlight .sb { color: #4070a0 }
+/* LiteralStringChar */ .highlight .sc { color: #4070a0 }
+/* LiteralStringDelimiter */ .highlight .dl { color: #4070a0 }
+/* LiteralStringDoc */ .highlight .sd { color: #4070a0; font-style: italic }
+/* LiteralStringDouble */ .highlight .s2 { color: #4070a0 }
+/* LiteralStringEscape */ .highlight .se { color: #4070a0; font-weight: bold }
+/* LiteralStringHeredoc */ .highlight .sh { color: #4070a0 }
+/* LiteralStringInterpol */ .highlight .si { color: #70a0d0; font-style: italic }
+/* LiteralStringOther */ .highlight .sx { color: #c65d09 }
+/* LiteralStringRegex */ .highlight .sr { color: #235388 }
+/* LiteralStringSingle */ .highlight .s1 { color: #4070a0 }
+/* LiteralStringSymbol */ .highlight .ss { color: #517918 }
+/* LiteralNumber */ .highlight .m { color: #40a070 }
+/* LiteralNumberBin */ .highlight .mb { color: #40a070 }
+/* LiteralNumberFloat */ .highlight .mf { color: #40a070 }
+/* LiteralNumberHex */ .highlight .mh { color: #40a070 }
+/* LiteralNumberInteger */ .highlight .mi { color: #40a070 }
+/* LiteralNumberIntegerLong */ .highlight .il { color: #40a070 }
+/* LiteralNumberOct */ .highlight .mo { color: #40a070 }
+/* Operator */ .highlight .o { color: #666666 }
+/* OperatorWord */ .highlight .ow { color: #007020; font-weight: bold }
+/* Comment */ .highlight .c { color: #60a0b0; font-style: italic }
+/* CommentHashbang */ .highlight .ch { color: #60a0b0; font-style: italic }
+/* CommentMultiline */ .highlight .cm { color: #60a0b0; font-style: italic }
+/* CommentSingle */ .highlight .c1 { color: #60a0b0; font-style: italic }
+/* CommentSpecial */ .highlight .cs { color: #60a0b0; background-color: #fff0f0 }
+/* CommentPreproc */ .highlight .cp { color: #007020 }
+/* CommentPreprocFile */ .highlight .cpf { color: #007020 }
+/* GenericDeleted */ .highlight .gd { color: #a00000 }
+/* GenericEmph */ .highlight .ge { font-style: italic }
+/* GenericError */ .highlight .gr { color: #ff0000 }
+/* GenericHeading */ .highlight .gh { color: #000080; font-weight: bold }
+/* GenericInserted */ .highlight .gi { color: #00a000 }
+/* GenericOutput */ .highlight .go { color: #888888 }
+/* GenericPrompt */ .highlight .gp { color: #c65d09; font-weight: bold }
+/* GenericStrong */ .highlight .gs { font-weight: bold }
+/* GenericSubheading */ .highlight .gu { color: #800080; font-weight: bold }
+/* GenericTraceback */ .highlight .gt { color: #0044dd }
+/* GenericUnderline */ .highlight .gl { text-decoration: underline }
+/* TextWhitespace */ .highlight .w { color: #bbbbbb }
 
 /*
     Dark mode customizes the "monokai" theme.
@@ -85,19 +85,19 @@
 
 .code-mode-dark {
 
-    /* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
-    /* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
-    /* LineHighlight */ .chroma .hl { display: block; width: 100%;background-color: #ffffcc }
-    /* LineNumbersTable */ .chroma .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
-    /* LineNumbers */ .chroma .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
-    /* KeywordNamespace */ .chroma .kn { color: #f92672 }
-    /* NameTag */ .chroma .nt { color: #f92672 }
-    /* OperatorWord */ .chroma .ow { color: #f92672 }
-    /* GenericDeleted */ .chroma .gd { color: #f92672 }
-    /* GenericEmph */ .chroma .ge { font-style: italic }
-    /* GenericStrong */ .chroma .gs { font-weight: bold }
+    /* LineTableTD */ .highlight .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
+    /* LineTable */ .highlight .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
+    /* LineHighlight */ .highlight .hl { display: block; width: 100%;background-color: #ffffcc }
+    /* LineNumbersTable */ .highlight .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
+    /* LineNumbers */ .highlight .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
+    /* KeywordNamespace */ .highlight .kn { color: #f92672 }
+    /* NameTag */ .highlight .nt { color: #f92672 }
+    /* OperatorWord */ .highlight .ow { color: #f92672 }
+    /* GenericDeleted */ .highlight .gd { color: #f92672 }
+    /* GenericEmph */ .highlight .ge { font-style: italic }
+    /* GenericStrong */ .highlight .gs { font-weight: bold }
 
-    .chroma {
+    .highlight {
 
         /* NameBuiltin */ .nb
         {
@@ -196,7 +196,7 @@
 
     &.code-pulumi {
 
-        .chroma {
+        .highlight {
 
             /* Name */ .n,
             /* Keyword */ .k,