_api-python.scss

//
// 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;
    }
}

// We rely on the Python docs that begin with `<div class="section" id="foo">` to target these styles.
div.section[id]:not([id=""]) {
    // 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 {
            // Hide the header link when not hovering.
            > a.headerlink {
                @apply invisible;
            }
        }

        dt {
            // Use the same styling as our `pre` tags for definitions.
            @apply font-mono bg-gray-100 py-4 px-5 rounded border border-gray-200 scrolling-auto overflow-scroll my-4 leading-normal text-sm;

            // 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;
                }
            }
        }
    }

    dl.field-list {
        @apply mb-8;

        dt {
            @apply py-1 pl-0 border-none bg-transparent font-body font-bold text-lg;
        }

        dd {
            @apply ml-4;
        }
    }

    table td, .pre {
        @apply break-words;
        word-break: break-word;
    }
}