Refactor Furo to use Sass nesting (#429)

Sass allows nesting: > When writing HTML you’ve probably noticed that it has a clear nested and visual hierarchy. CSS, on the other hand, doesn’t. > > Sass will let you nest your CSS selectors in a way that follows the same visual hierarchy of your HTML. E.g. ```scss nav { ul { margin: 0; padding: 0; list-style: none; } li { display: inline-block; } } ``` vs. ```css nav ul { margin: 0; padding: 0; list-style: none; } nav li { display: inline-block; } ``` This cleans up some of our hard-to-read selectors.
Qiskit · Jun 29, 2023 · 111783f · 111783f
1 parent 3776a32
commit 111783f
Show file tree

Hide file tree

Showing 6 changed files with 198 additions and 210 deletions.
diff --git a/src/qiskit_sphinx_theme/assets/styles/_admonitions.scss b/src/qiskit_sphinx_theme/assets/styles/_admonitions.scss
@@ -13,19 +13,18 @@ body {
     --qiskit-color-admonition-error--border: #da1e28;
 }
 
-
 .topic {
   border: 1px solid var(--qiskit-color-admonition-info--background);
 }
 
-p.topic-title::before {
-  -webkit-mask-image: var(--icon-info);
-  mask-image: var(--icon-info);
-  background-color: var(--qiskit-color-admonition-info--border);
-}
-
 p.topic-title {
   background-color: var(--qiskit-color-admonition-info--background);
+
+  &::before {
+    -webkit-mask-image: var(--icon-info);
+    mask-image: var(--icon-info);
+    background-color: var(--qiskit-color-admonition-info--border);
+  }
 }
 
 // Admonitions are complex because they use a 3px left border with a different color than the rest
@@ -45,92 +44,81 @@ p.topic-title {
   border-bottom-width: 1px;
   position: relative;
   padding-left: 12px;
-}
-.admonition::before {
-  content: '';
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  left: 0;
-  width: 3px;
-}
 
-.admonition.attention > .admonition-title::before,
-.admonition.caution > .admonition-title::before,
-.admonition.important > .admonition-title::before,
-.admonition.warning > .admonition-title::before {
-  // Rather than using mask-image like Furo normally does, we set `content` to the SVG. This is
-  // because Carbon requires that we have a black exclamation mark for accessibility: the
-  // light yellow background wouldn't be distinct enough compared to the dark yellow icon. Mask
-  // image doesn't let us set colors, only whether to use the background color of the underlying
-  // HTML element vs. use the background color of the SVG container. So, having a black exclamation
-  // mark would require setting the entire .admonition-title background color to black.
-  content: var(--icon-warning);
-  -webkit-mask-image: unset;
-  mask-image: unset;
-  background-color: var(--qiskit-color-admonition-warning--background);
-}
-.admonition.attention > .admonition-title,
-.admonition.caution > .admonition-title,
-.admonition.important > .admonition-title,
-.admonition.warning > .admonition-title {
-  background-color: var(--qiskit-color-admonition-warning--background);
+  &::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    width: 3px;
+  }
 }
+
 .admonition.attention,
 .admonition.caution,
 .admonition.important,
 .admonition.warning {
   border-color: var(--qiskit-color-admonition-warning--background);
-}
-.admonition.attention::before,
-.admonition.caution::before,
-.admonition.important::before,
-.admonition.warning::before {
-  background: var(--qiskit-color-admonition-warning--border);
-}
 
-.admonition.danger > .admonition-title::before,
-.admonition.error > .admonition-title::before {
-  -webkit-mask-image: var(--icon-failure);
-  mask-image: var(--icon-failure);
-  background-color: var(--qiskit-color-admonition-error--border);
-}
-.admonition.danger > .admonition-title,
-.admonition.error > .admonition-title {
-  background-color: var(--qiskit-color-admonition-error--background);
+  &::before {
+    background: var(--qiskit-color-admonition-warning--border);
+  }
+
+  > .admonition-title {
+    background-color: var(--qiskit-color-admonition-warning--background);
+  }
+
+  > .admonition-title::before {
+    // Rather than using mask-image like Furo normally does, we set `content` to the SVG. This is
+    // because Carbon requires that we have a black exclamation mark for accessibility: the
+    // light yellow background wouldn't be distinct enough compared to the dark yellow icon. Mask
+    // image doesn't let us set colors, only whether to use the background color of the underlying
+    // HTML element vs. use the background color of the SVG container. So, having a black exclamation
+    // mark would require setting the entire .admonition-title background color to black.
+    content: var(--icon-warning);
+    -webkit-mask-image: unset;
+    mask-image: unset;
+    background-color: var(--qiskit-color-admonition-warning--background);
+  }
 }
+
 .admonition.danger,
 .admonition.error {
   border-color: var(--qiskit-color-admonition-error--background);
-}
-.admonition.danger::before,
-.admonition.error::before {
-  background: var(--qiskit-color-admonition-error--border);
-}
 
-.admonition > .admonition-title::before,
-.admonition.hint > .admonition-title::before,
-.admonition.note > .admonition-title::before,
-.admonition.tip > .admonition-title::before {
-  -webkit-mask-image: var(--icon-info);
-  mask-image: var(--icon-info);
-  background-color: var(--qiskit-color-admonition-info--border);
-}
-.admonition > .admonition-title,
-.admonition.hint > .admonition-title,
-.admonition.note > .admonition-title,
-.admonition.tip > .admonition-title {
-  background-color: var(--qiskit-color-admonition-info--background);
+  &::before {
+    background: var(--qiskit-color-admonition-error--border);
+  }
+
+  > .admonition-title {
+    background-color: var(--qiskit-color-admonition-error--background);
+  }
+
+  > .admonition-title::before {
+    -webkit-mask-image: var(--icon-failure);
+    mask-image: var(--icon-failure);
+    background-color: var(--qiskit-color-admonition-error--border);
+  }
 }
+
 .admonition,
 .admonition.hint,
 .admonition.note,
 .admonition.tip {
   border-color: var(--qiskit-color-admonition-info--background);
-}
-.admonition::before,
-.admonition.hint::before,
-.admonition.note::before,
-.admonition.tip::before {
-  background: var(--qiskit-color-admonition-info--border);
+
+  &::before {
+    background: var(--qiskit-color-admonition-info--border);
+  }
+
+  > .admonition-title {
+    background-color: var(--qiskit-color-admonition-info--background);
+  }
+
+  > .admonition-title::before {
+    -webkit-mask-image: var(--icon-info);
+    mask-image: var(--icon-info);
+    background-color: var(--qiskit-color-admonition-info--border);
+  }
 }
diff --git a/src/qiskit_sphinx_theme/assets/styles/_api.scss b/src/qiskit_sphinx_theme/assets/styles/_api.scss
@@ -2,7 +2,6 @@
 body {
   --color-api-name: var(--color-foreground-primary);
   --color-api-pre-name: var(--color-foreground-secondary);
-
 }
 
 // Definition lists are used for sections like "Parameters", "Return type", and "Attributes"
@@ -16,38 +15,43 @@ dl.py:not(.docutils) dt {
 }
 
 // Rules that impact the top-level entry for the code object, which e.g. has the `[source]` button.
-section > dl.py:not(.docutils) > dt {
-  // We normally want to use inline-block for definition terms so that the purple border we add on
-  // top does not stretch across the whole screen. But, we make an exception here it will have a
-  // `[source]` button that floats to the right. The spacing of that is non-trivial and was the
-  // source of issues in Pytorch, so we stick with Furo's spacing.
-  display: block;
-  // Make the border less thick so its clear the top-level page header corresponds to this line.
-  border-top-width: 1px;
-  margin-bottom: 1rem;
-}
-// It's possible to have multiple entries for the same code object, e.g. when using typing.overload.
-// This cancels out the margin-bottom such that only the bottom-most `dt` will have a margin-bottom
-// in effect.
-section > dl.py:not(.docutils) > dt:not(:first-child) {
-  margin-top: -1rem;
+section > dl.py:not(.docutils) {
+  > dt {
+    // We normally want to use inline-block for definition terms so that the purple border we add on
+    // top does not stretch across the whole screen. But, we make an exception here it will have a
+    // `[source]` button that floats to the right. The spacing of that is non-trivial and was the
+    // source of issues in Pytorch, so we stick with Furo's spacing.
+    display: block;
+    // Make the border less thick so its clear the top-level page header corresponds to this line.
+    border-top-width: 1px;
+    margin-bottom: 1rem;
+  }
+
+  // It's possible to have multiple entries for the same code object, e.g. when using typing.overload.
+  // This cancels out the margin-bottom such that only the bottom-most `dt` will have a margin-bottom
+  // in effect.
+  > dt:not(:first-child) {
+    margin-top: -1rem;
+  }
 }
 
 // Fix some of the definition terms like "Parameters" having no padding and being in all caps.
-//
-// Some Qiskit projects, like Experiments, use custom API sections. Those don't set the class
-// `.field-list` on the `dl`, so we change Furo's selector from `.field-list > dt` to `dl > dt`. But,
-// to override Furo's properties we don't like, we also have to use `.field-list > dt` for some
-// rules to win the specificity war.
-dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl > dt {
-  font-weight: 700;
-  // Copied from Furo's `.sig:not(.sig-inline)`
-  padding: .25rem .5rem .25rem 3em;
-  text-indent: -2.5em;
-}
-dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list > dt {
-  text-transform: unset;
-  font-size: unset;
+dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) {
+  //  Some Qiskit projects, like Experiments, use custom API sections. Those don't set the class
+  // `.field-list` on the `dl`, so we change Furo's selector from `.field-list > dt` to `dl > dt`.
+  dl > dt {
+    font-weight: 700;
+    // Copied from Furo's `.sig:not(.sig-inline)`
+    padding: .25rem .5rem .25rem 3em;
+    text-indent: -2.5em;
+  }
+
+  // But, to override Furo's properties we don't like, we also have to use `.field-list > dt` for some
+  // rules to win the specificity war.
+  .field-list > dt {
+    text-transform: unset;
+    font-size: unset;
+  }
 }
 
 .sig:not(.sig-inline) {

diff --git a/src/qiskit_sphinx_theme/assets/styles/_layout.scss b/src/qiskit_sphinx_theme/assets/styles/_layout.scss
@@ -32,6 +32,10 @@ body {
   flex: 0 0 var(--qiskit-left-sidebar-width);
   width: var(--qiskit-left-sidebar-width);
   min-width: var(--qiskit-left-sidebar-width);
+
+  @media (max-width: 67em) {
+    left: calc(var(--qiskit-left-sidebar-width) * -1);
+  }
 }
 
 .sidebar-container {
@@ -46,9 +50,3 @@ body {
 .toc-drawer {
   flex: 0 0 15em;
 }
-
-@media (max-width: 67em) {
-  .sidebar-drawer {
-    left: calc(var(--qiskit-left-sidebar-width) * -1);
-  }
-}