Skip to content

API doc styling improvements #1247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 27, 2019
Merged

API doc styling improvements #1247

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
31c34c9
Update API doc styling for Python
justinvp Jun 27, 2019
f1d8716
Only emit the <h1>.Title</h1> if there is a .Title
justinvp Jun 27, 2019
63fcebb
Update API doc styling for Node.js
justinvp Jun 27, 2019
feb180f
Update _pygments.scss to select .highlight instead of .chroma
justinvp Jun 27, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions assets/sass/_api-nodejs.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
}
}
}
}
119 changes: 119 additions & 0 deletions assets/sass/_api-python.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
}
}
}
}
}
160 changes: 80 additions & 80 deletions assets/sass/_pygments.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,93 +11,93 @@
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.
*/

.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
{
Expand Down Expand Up @@ -196,7 +196,7 @@

&.code-pulumi {

.chroma {
.highlight {

/* Name */ .n,
/* Keyword */ .k,
Expand Down
2 changes: 2 additions & 0 deletions assets/sass/styles.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
@import "mixins";

@import "animation";
@import "api-nodejs";
@import "api-python";
@import "buttons";
@import "code";
@import "fonts";
Expand Down
5 changes: 4 additions & 1 deletion layouts/docs/list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,10 @@
</div>

<div class="md:w-7/12">
<h1>{{ .Title }}</h1>
{{ if ne .Title "" }}
<h1>{{ .Title }}</h1>
{{ end }}

{{ .Content }}
</div>
</div>
Expand Down