_theme_rst.sass

// -------------------------------------------------------------------------------------------------------------------
// CONTRIBUTORS, PLEASE READ THIS!
// -------------------------------------------------------------------------------------------------------------------
// Couple things...
//    1. Lots of this @extends from wyrm_core/_type.sass (http://www.github.com/snide/wyrm/.
//        * Try not to replace any @extends code. It's pretty generic stuff meant to work together.
//        * That said, know that I'm very unlikely to accept PRs from wyrm just to change style here.
//    2. I plan to remove the !importants in here. Part of it is due to laziness, part to sphinx's fondness for nesting.
//    3. Try to use variables from wyrm_core/wy_variables.sass. Notable are...
//        * $base-line-height // All margins, padding and line-height should use this in .25 increments.
//        * $text-color, $text-light, $text-dark...etc
//        * $base-font-family, $custom-font-family, $code-font-family
//    4. If you have changes for mobile/tablet, put them at the bottom of the sass file.
// --------------------------------------------------------------------------------------------------------------------

.rst-content
  // Some browsers like to give arbitrary margins :( make them all consistent.
  h1, h2, h3, h4, h5, h6
    margin-bottom: $base-line-height

  // Sphinx by default applies HxW style attributes to images. This fixes that oversite.
  img
    max-width: 100%
    height: auto

  div.figure, figure
    margin-bottom: $base-line-height
    .caption-text
      font-style: italic
    p:last-child.caption
      margin-bottom: 0px
    &.align-center
      text-align: center

  // Usually it's a good idea to give images some space.
  .section >, section >
    img, a > img
      margin-bottom: $base-line-height

  // normalize browser styling
  abbr[title]
    text-decoration: none

  // Style external links
  &.style-external-links a.reference.external:after
    font-family: FontAwesome
    content: "\f08e"
    color: $text-light
    vertical-align: super
    font-size: 60%
    margin: 0 0.2em

  // For the most part, its safe to assume that sphinx wants you to use a blockquote as an indent. It gets
  // used in many different ways, so don't assume you can apply some fancy style, just leave it be.
  blockquote
    margin-left: $base-line-height
    line-height: $base-line-height
    margin-bottom: $base-line-height

  pre.literal-block
    white-space: pre
    margin: 0
    padding: ($base-line-height / 2) ($base-line-height / 2)
    font-family: $code-font-family
    display: block
    overflow: auto
  pre.literal-block, div[class^='highlight']
    border: 1px solid $table-border-color
    overflow-x: auto
    // 1px hack otherwise border won't show. lame
    margin: 1px 0 $base-line-height 0
    div[class^='highlight']
      padding: 0px
      border: none
      margin: 0
  // Needs 100% width for line highlighting to work properly
  div[class^='highlight'] td.code
    width: 100%
  .linenodiv pre
    border-right: solid 1px lighten($table-border-color, 2%)
    margin: 0
    padding: ($base-line-height / 2) ($base-line-height / 2)
    font-family: $code-font-family
    user-select: none
    pointer-events: none
  div[class^='highlight'] pre
    white-space: pre
    margin: 0
    padding: ($base-line-height / 2) ($base-line-height / 2)
    display: block
    overflow: auto
    & .hll
      // Line emphasis spans full width
      display: block
      margin: 0 (-1 * $base-line-height / 2)
      padding: 0 ($base-line-height / 2)
  pre.literal-block, div[class^='highlight'] pre, .linenodiv pre
    font-family: $code-font-family
    font-size: 12px
    line-height: 1.4

  // Do not allow selection of code block prompts and line numbers
  div.highlight
    span.linenos, .gp
      user-select: none
      pointer-events: none

    span.linenos
      display: inline-block
      padding-left: 0px
      padding-right: ($base-line-height / 2)
      margin-right: ($base-line-height / 2)
      border-right: 1px solid lighten($table-border-color, 2%)

  .code-block-caption
    font-style: italic
    font-size: 85%
    line-height: 1
    padding: 1em 0
    text-align: center

  @media print
    .codeblock, div[class^='highlight'], div[class^='highlight'] pre
      white-space: pre-wrap

  // These are the various note pullouts that sphinx applies
  .note, .attention, .caution, .danger, .error, .hint, .important, .tip, .warning, .seealso, .admonition-todo, .admonition
    @extend .wy-alert
    // These block elements are unsuitable for having floating objects next
    // to them
    clear: both
    .last, > *:last-child
      margin-bottom: 0
  .admonition-title
    @extend .wy-alert-title
    @extend .fa
    @extend .fa-exclamation-circle
    &:before
      margin-right: 4px
  .note, .seealso
    @extend .wy-alert.wy-alert-info
  .hint, .tip, .important
    @extend .wy-alert.wy-alert-success
  .error, .danger
    @extend .wy-alert.wy-alert-danger
  .warning, .caution, .attention, .admonition-todo
    @extend .wy-alert.wy-alert-warning
  // Some people put tables in notes. Let's give them very basic support.
  .admonition table
    border-color: rgba(0, 0, 0, 0.1)
    td, th
      background: transparent !important
      border-color: rgba(0, 0, 0, 0.1) !important

  .section, section, .toctree-wrapper
    ul
      @extend .wy-plain-list-disc
    ol.loweralpha, ol.loweralpha > li
      list-style: lower-alpha
    ol.upperalpha, ol.upperalpha > li
      list-style: upper-alpha
    ol, ol.arabic
      @extend .wy-plain-list-decimal
    // Complex bullet lists, they have more item margins than simple lists
    ol li, ul li
      > *
        margin-top: $base-line-height / 2
        margin-bottom: $base-line-height / 2
        &:first-child
          margin-top: 0rem
      > p
        &, &:last-child
          margin-bottom: $base-line-height / 2
        &:only-child, &:only-child:last-child
          margin-bottom: 0rem
      > ul, > ol
        margin-bottom: $base-line-height / 2
    // Simple lists, no item margins
    ol.simple li, ul.simple li
      > *
        margin-top: 0rem
        margin-bottom: 0rem
      ul, ol
        margin-top: 0rem
        margin-bottom: 0rem

  .line-block
    margin-left: 0px
    margin-bottom: $base-line-height
    line-height: $base-line-height
  .line-block .line-block
    margin-left: $base-line-height
    margin-bottom: 0px

  // Generics handling of headings and toc stuff.
  .topic-title
    font-weight: bold
    margin-bottom: $base-line-height / 2
  .toc-backref
    color: $text-color
  .align-right
    float: right
    margin: 0px 0px $base-line-height $base-line-height
  .align-left
    float: left
    margin: 0px $base-line-height $base-line-height 0px
  .align-center
    margin: auto
    // Do not override display:table for tables
    &:not(table)
      display: block
  .toctree-wrapper > p.caption
    @extend h2

  // This is the #href that shows up on hover. Sphinx's is terrible so I hack it away.
  h1, h2, h3, h4, h5, h6, dl dt, p, p.caption, table > caption, .code-block-caption, .eqno
    .headerlink
      opacity: 0
      font-size: 14px
      font-family: FontAwesome
      margin-left: 0.5em
      @extend .fa
      &:focus
        opacity: 1
    &:hover .headerlink
      opacity: 1

  // Make links inside paragraphs wrap when they are too long
  p a
    overflow-wrap: anywhere
  // Consistent font sizing for table typography
  .wy-table
    th, td
      p, ul
          font-size: inherit

  // override the Wyrm accessibility anti-pattern of hiding button focus
  .btn:focus
    outline: 2px solid

  table > caption .headerlink:after
    font-size: 12px

  .centered
    text-align: center

  // Sidebar content. You'll see at the bottom of this file I change it in mobile.
  .sidebar
    float: right
    width: 40%
    display: block
    margin: 0 0 $base-line-height $base-line-height
    padding: $base-line-height
    background: $sidebar-background-color
    border: solid 1px $sidebar-border-color
    // Sidebar content is usually less relevant, so adjust the margins and sizes.
    p, ul, dl
      font-size: 90%
    .last, > *:last-child
      margin-bottom: 0
    .sidebar-title
      display: block
      font-family: $custom-font-family
      font-weight: bold
      background: $table-border-color
      padding: ($base-line-height / 4) ($base-line-height / 2)
      margin: -$base-line-height
      margin-bottom: $base-line-height
      font-size: 100%
  // Sphinx can highlight searched text with ?highlighted=searchterm
  .highlighted
    background: $highlight-color
    box-shadow: 0 0 0 ($base-line-height / 12) $highlight-color
    display: inline
    font-weight: bold

  // These are the little citation links [1] that show up within paragraphs.
  .footnote-reference, .citation-reference
    vertical-align: baseline
    position: relative
    top: -0.4em
    line-height: 0
    font-size: 90%
    > span.fn-bracket
      display: none

  // Horizontal lists have multiple columns; use full width
  .hlist
    width: 100%

  // Definition lists term/classifier separator
  // Adds a separator for Sphinx > 1.x as a pseudo-element
  // and hides the hardcoded separator from Sphinx 1.x
  dl dt span.classifier
    &:before
      content: " : "
  dl dt span.classifier-delimiter
    display: none !important

  // The html4 writer outputs the citation and footnotes as a table, and the
  // html5 writer outputs these as a definition list (docutils < 0.18) or an
  // aside/div (docutils 0.18+). We will use the fairly well supported css
  // `grid` attributes to make these back into a table
  // HTML4 writer
  html.writer-html4 &
    table.docutils.citation, table.docutils.footnote
      background: none
      border: none
      td, tr
        border: none
        background-color: transparent !important
        white-space: normal
      td.label
        padding-left: 0
        padding-right: 0
        vertical-align: top
  // HTML5 writer
  html.writer-html5 &
    // docutils < 0.18 grid layout. Some spacing is the dl/dt/dd margins
    dl.footnote, dl.citation, dl.field-list
      display: grid
      grid-template-columns: auto minmax(80%, 95%)
      > dt
        display: inline-grid
        grid-template-columns: max-content auto
    // docutils => 0.18 grid layout
    aside.footnote, aside.citation, div.citation
      display: grid
      // Two any width columns for label and backrefs, a noop column to expand
      // to fill the width allocated to the first two columns, and then the
      // content column for the paragraphs.
      grid-template-columns: auto auto minmax(0.65rem, auto) minmax(40%, 95%)
      & > span.label
        grid-column-start: 1
        grid-column-end: 2
      & > span.backrefs
        grid-column-start: 2
        grid-column-end: 3
        grid-row-start: 1
        grid-row-end: 3
      & > p
        grid-column-start: 4
        grid-column-end: 5

    // Shared backrefs styling for docutils versions
    @mixin footnote-backrefs
      text-align: left
      font-style: italic
      margin-left: .65rem
      word-break: break-word
      word-spacing: -0.1rem
      max-width: 5rem

      > a
        &:not(:first-child)::before
          content: " " 
        word-break: keep-all

    // docutils < 0.18 html5 writer styling
    dl.footnote, dl.citation, dl.field-list,
      margin-bottom: $base-line-height
      > dt
        padding-left: 1rem
      > dt, > dd
        margin-bottom: 0rem
    dl.footnote, dl.citation
      font-size: .9rem
      > dt
        margin: 0rem 0.5rem 0.5rem 0rem
        line-height: 1.2rem
        word-break: break-all
        font-weight: normal
        > span.brackets
          &:before
            content: "["
          &:after
            content: "]"
        > span.fn-backref
          @include footnote-backrefs
      > dd
        margin: 0rem 0rem 0.5rem 0rem
        line-height: 1.2rem
        p
          font-size: 0.9rem

    // docutils => 0.18 html5 writer styling
    aside.footnote, aside.citation, div.citation
      padding-left: 1rem
      padding-right: 1rem
      font-size: 0.9rem
      line-height: 1.2rem
      p
        font-size: 0.9rem
        line-height: 1.2rem
        margin-bottom: $base-line-height / 2
      span.backrefs
        @include footnote-backrefs
      span.label
        line-height: 1.2rem
    aside.footnote-list, aside.citation-list, div.citation-list
      margin-bottom: $base-line-height

    dl.option-list
      kbd
        font-size: 0.9rem
  // Both
  html.writer-html4 & table.docutils.citation, table.docutils.footnote,
  html.writer-html5 & dl.footnote,
  html.writer-html5 & dl.citation,
  html.writer-html5 & aside.footnote,
  html.writer-html5 & aside.footnote-list aside.footnote,
  html.writer-html5 & div.citation-list > div.citation
    color: $text-medium
    code
      color: $gray

  // Remove the large vertical space between citations and footnotes
  .wy-table-responsive.citation, .wy-table-responsive.footnote
    margin-bottom: 0
  // Re-add vertical space to element directly following citation and footnotes,
  // if the following element is of a different type
  .wy-table-responsive.citation + :not(.citation),
  .wy-table-responsive.footnote + :not(.footnote)
    margin-top: $base-line-height
  // Re-add vertical space after citation and footnotes if it is the last child of a parent
  .wy-table-responsive.citation:last-child, .wy-table-responsive.footnote:last-child
    margin-bottom: $base-line-height
  table.docutils
    @extend .wy-table
    @extend .wy-table-bordered-all
    th
      border-color: $table-border-color
      html.writer-html5 &
        border: 1px solid $table-border-color
    html.writer-html5 &
      th > p, td > p
        line-height: 1rem
        margin-bottom: 0rem
        font-size: 0.9rem
    &:not(.field-list)
      @extend .wy-table-striped
    // Remove bottom margin for the last element (and it's last child)
    td .last, td .last > *:last-child
      margin-bottom: 0
  // This table is what gets spit out for auto-generated API stuff. I style it smaller bits of padding.
  table.field-list
    @extend .wy-table
    border: none
    td
      border: none
      p
        line-height: inherit
    td > strong
      display: inline-block
    .field-name
      padding-right: 10px
      text-align: left
      white-space: nowrap
    .field-body
      text-align: left

  // These are the "literals" that get spit out when you mark stuff as ``code`` as your write.
  tt, code
    @extend code
    color: $black
    font-family: $code-font-family
    padding: 2px 5px
    big, em
      font-size: 100% !important
      line-height: normal

    &.literal
      color: $text-code-color
      white-space: normal
    &.xref, a &
      font-weight: bold
      color: $text-codexref-color
      // https://github.com/readthedocs/sphinx_rtd_theme/issues/1368
      overflow-wrap: normal
  pre, kbd, samp
    font-family: $code-font-family
  // If the literal is inside an a tag, let's color it like a link
  a tt, a code
    color: $link-color
  dl
    margin-bottom: $base-line-height
    dt
      font-weight: bold
      margin-bottom: $base-line-height / 2
    // Most of the content within these dls are one liners, so I halve the normal margins.
    p, table, ul, ol
      margin-bottom: $base-line-height / 2
    // rST seems to want dds to be treated as the browser would, indented.
    dd
      margin: 0 0 ($base-line-height / 2) $base-line-height
      line-height: $base-line-height
      > p:last-child,
      > ol:last-child,
      > ul:last-child,
      > table:last-child
        margin-bottom: 0
  html.writer-html4 & dl:not(.docutils),
  html.writer-html5 & dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)
    margin-bottom: $base-line-height
    > dt
      display: table
      margin: ($base-line-height / 4) 0
      font-size: 90%
      line-height: normal
      background: lighten($class-color, 50%)
      color: $class-color
      border-top: solid 3px lighten($class-color, 20%)
      padding: $base-line-height / 4
      position: relative
      &:before
        color: lighten($class-color, 20%)
      .headerlink
        color: $text-color
        font-size: 100% !important
    // In the html4 writer, parameters is a table. In html5 writer, parameters
    // is a nested dl.field-list
    dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt
      margin-bottom: $base-line-height / 4
      border: none
      border-left: solid 3px hsl(0, 0%, 80%)
      background: hsl(0, 0%, 94%)
      color: $method-color
      .headerlink
        color: $headerlink-color
        font-size: 100% !important
    > dt:first-child
      margin-top: 0
    // Since dts get the callout style, we treat this less as callouts.
    tt, code
      &.descname, &.descclassname
        background-color: transparent
        border: none
        padding: 0
        font-size: 100% !important
      &.descname
        font-weight: bold
    // This is for more advanced parameter control
    .optional
      display: inline-block
      padding: 0 4px
      color: $black
      font-weight: bold
    .property
      display: inline-block
      padding-right: 8px
      max-width: 100%
    // This is keywords such as "const"
    .k
      font-style: italic
    .sig-name, .descname, .descclassname
      font-family: $code-font-family
      color: $black
  // Doc links to sourcecode
  .viewcode-link, .viewcode-back
    display: inline-block
    color: $text-viewcode-color
    font-size: 80%
    padding-left: $base-line-height
  .viewcode-back
    display: block
    float: right
  p.rubric
    margin-bottom: 12px
    font-weight: bold
  //Download link
  code.download
    background: inherit
    padding: inherit
    font-weight: normal
    font-family: inherit
    font-size: inherit
    color: inherit
    border: inherit
    white-space: inherit
    span:first-child
      -webkit-font-smoothing: subpixel-antialiased
      @extend .fa
      @extend .fa-download
      &:before
        margin-right: 4px
  .guilabel
    border: 1px solid lighten($guilabel-color, 25%)
    background: lighten($guilabel-color, 50%)
    font-size: 80%
    font-weight: 700
    border-radius: $base-line-height / 6
    padding: ($base-line-height / 10) ($base-line-height / 4)
    margin: auto ($base-line-height / 12)
  *:not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > kbd,
  *:not(dl.option-list) > :not(dt):not(kbd):not(.kbd) > .kbd
    color: inherit
    font-size: 80%
    background-color: lighten($text-light, 30%)
    border: 1px solid darken($text-light, 5%)
    border-radius: $base-line-height / 6
    box-shadow: grey 0px $base-line-height / 12
    padding: $base-line-height / 10 $base-line-height / 4
    margin: auto 0
  .versionmodified
    font-style: italic


// Mobile specific
+media($mobile)
  .rst-content
    .sidebar
      width: 100%