MAINT: fixes to tabbed examples in docs (#1379)

* capitalize tab titles * add overline hover effect to tabs * make rST/md examples match * prevent spurious link to conf.py
pydata · Jul 3, 2023 · 92445e9 · 92445e9
1 parent e9f248c
commit 92445e9
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 25 deletions.
diff --git a/docs/community/topics/page-metadata.md b/docs/community/topics/page-metadata.md
@@ -8,12 +8,12 @@ This is [similar to how the TOML language defines nested configuration](https://
 For example, to remove the secondary sidebar, we use a page metadata key like this:
 
 `````{tab-set}
-````{tab-item} rst
+````{tab-item} rST
 ```rst
 :html_theme.sidebar_secondary.remove: true
 ```
 ````
-````{tab-item} markdown
+````{tab-item} Markdown
 ```md
 ---
 html_theme.sidebar_secondary.remove: true

diff --git a/docs/user_guide/static_assets.md b/docs/user_guide/static_assets.md
@@ -35,7 +35,9 @@ They will be added to the end of the `<head>` of your site.
 For example:
 
 ```{code-block} python
-:caption: conf.py
+---
+caption: '`conf.py`'
+---
 
 html_static_path = ["_static"]
 html_css_files = ["mycss.css"]
@@ -59,7 +61,9 @@ In addition, `app.add_js_file` allows you to add _raw JavaScript_ in addition to
 For example:
 
 ```{code-block} python
-:caption: conf.py
+---
+caption: '`conf.py`'
+---
 
 html_static_path = ["_static"]
 
@@ -87,7 +91,9 @@ If you run `app.add_js_file` or `app.add_css_file`, it will _only be added for t
 For example:
 
 ```{code-block} python
-:caption: conf.py
+---
+caption: '`conf.py`'
+---
 html_static_path = ["_static"]
 
 def add_my_files(app, pagename, templatename, context, doctree):
@@ -103,28 +109,35 @@ def setup(app):
 ## Add it directly to the page content
 
 Finally, you can add CSS or JS directly to a page's content.
-If you're using either the raw directive (reStructuredText) or pure html (MyST Markdown).
+If you're using reStructuredText you can use the `.. raw::` directive; if you're using MyST Markdown you can simply include the HTML content in-line with your Markdown-formatted content.
 
 ``````{tab-set}
-`````{tab-item} rst
+`````{tab-item} rST
 ````{code-block} rst
 :caption: some_page_in_my_site.rst
+My title
+========
+
+Some text
+
 .. raw:: html
 
-   <style>
-   .myclass {
-    font-size: 2rem;
-   }
+    <style>
+      /* Make h2 bigger */
+      h2 {
+        font-size: 3rem;
+      }
+    </style>
 
-   </style>
-   <script>
-   console.log("hi!")
-   </script>
+A bigger title
+--------------
+
+Some other text
 ````
 `````
-`````{tab-item} markdown
+`````{tab-item} Markdown
 ````{code-block} md
-:caption: other_page_in_my_site.md
+:caption: some_page_in_my_site.md
 # My title
 
 Some text

diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md
@@ -61,15 +61,15 @@ You can also provide captions with code blocks, which will be displayed right ab
 For example, the following code:
 
 ``````{tab-set}
-`````{tab-item} rst
+`````{tab-item} rST
 ````rst
 .. code-block:: python
     :caption: python.py
 
     print("A code block with a caption.")
 ````
 `````
-`````{tab-item} markdown
+`````{tab-item} Markdown
 ````md
 ```{code-block} python
 :caption: python.py
@@ -92,7 +92,7 @@ You can also display line numbers.
 For example, the following code:
 
 ``````{tab-set}
-`````{tab-item} rst
+`````{tab-item} rST
 ````rst
 ..  code-block:: python
     :caption: python.py
@@ -103,7 +103,7 @@ For example, the following code:
     print("A code block with a caption and line numbers.")
 ````
 `````
-`````{tab-item} markdown
+`````{tab-item} Markdown
 ````md
 ```{code-block} python
 :caption: python.py
@@ -183,15 +183,15 @@ To make an admonition behave like a sidebar, add the `sidebar` class to its list
 The admonition sidebar in this section was created with the following Markdown:
 
 ``````{tab-set}
-`````{tab-item} rst
+`````{tab-item} rST
 ````rst
 .. admonition:: A sidebar admonition!
     :class: sidebar note
 
     Some sidebar content.
 ````
 `````
-`````{tab-item} markdown
+`````{tab-item} Markdown
 ````md
 ```{admonition} A sidebar admonition!
 :class: sidebar note

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -158,7 +158,7 @@ html[data-theme="light"] {
   > input {
     // Active tab label
     &:checked + label {
-      border-color: var(--pst-color-primary);
+      border-color: transparent transparent var(--pst-color-primary); // top LR bottom
       color: var(--pst-color-primary);
     }
 
@@ -172,7 +172,8 @@ html[data-theme="light"] {
   // Tab label
   > label {
     color: var(--pst-color-text-muted);
-
+    border-top: 0.125rem solid transparent; // so hover isn't just color change
+    padding-top: 0.5em; // same as bottom padding, so hover overline looks OK
     // Hovered label
     html &:hover {
       color: var(--pst-color-secondary);