Tune stylesheets, video directive, print rules

To enhance webpage printing/pdf generation: * Add video admonition to replace non-function iframes/embed video. * Add print media queries to tune the styling * Limit background to media screen. Also, use width-content css var as a better breakpoint to the mobile format. Signed-off-by: Jorge Marques <[email protected]>
analogdevicesinc · Sep 10, 2024 · a6376f6 · a6376f6
1 parent fc9df4d
commit a6376f6
Show file tree

Hide file tree

Showing 14 changed files with 163 additions and 30 deletions.
diff --git a/adi_doctools/__init__.py b/adi_doctools/__init__.py
@@ -11,7 +11,7 @@
 from .role import setup as role_setup
 from .lut import get_lut
 
-__version__ = "0.3.41"
+__version__ = "0.3.42"
 
 logger = logging.getLogger(__name__)
 

diff --git a/adi_doctools/directive/common.py b/adi_doctools/directive/common.py
@@ -10,7 +10,7 @@
 from hashlib import sha1
 from typing import Tuple
 
-from .node import node_div, node_input, node_label, node_icon, node_source
+from .node import node_div, node_input, node_label, node_icon, node_source, node_a
 from .node import node_iframe, node_video
 
 logger = logging.getLogger(__name__)
@@ -245,13 +245,17 @@ def run(self):
             )
             yt_id = yt_match.group(3)
             iframe = node_iframe(
-                src=f"https://www.youtube-nocookie.com/embed/{yt_id}"
+                src=f"https://www.youtube-nocookie.com/embed/{yt_id}",
+                classes=['only-screen']
             )
             node += iframe
         else:
-            node = node_div()
+            node = node_div(
+                classes=['embed-video']
+            )
             video = node_video(
-                controls="controls"
+                controls="controls",
+                classes=['only-screen']
             )
             source = node_source(
                 type="video/mp4",
@@ -260,6 +264,30 @@ def run(self):
             video += source
             node += video
 
+        node_ = nodes.inline(
+            classes=['only-screen']
+        )
+        self.state.nested_parse(self.content, self.content_offset, node_)
+        node += node_
+
+        # Generate a video admonition for print
+        adm = node_div(
+            classes=['admonition', 'video', 'only-print']
+        )
+        adm += nodes.paragraph(
+            text="Video",
+            classes=["admonition-title"]
+        )
+
+        video_link = node_a(href=url)
+        video_link += nodes.inline(text=url)
+
+        self.state.nested_parse(self.content, self.content_offset, adm)
+        node_ = nodes.paragraph()
+        node_ += video_link
+        adm += node_
+        node += adm
+
         return [node]
 
 

diff --git a/adi_doctools/directive/node.py b/adi_doctools/directive/node.py
@@ -57,8 +57,12 @@ class node_iframe(node_base):
     tagname = 'iframe'
     endtag = 'false'
 
+class node_a(node_base):
+    tagname = 'a'
+    endtag = 'true'
+
 def node_setup(app):
-    for node in [node_div, node_input, node_label, node_icon, node_video, node_source, node_iframe]:
+    for node in [node_div, node_input, node_label, node_icon, node_video, node_source, node_iframe, node_a]:
         app.add_node(node,
                 html =(node.visit, node.depart),
                 latex=(node.visit, node.depart),

diff --git a/adi_doctools/theme/cosmic/style/bundle.scss b/adi_doctools/theme/cosmic/style/bundle.scss
@@ -10,3 +10,4 @@
 @import "footer";
 @import "related";
 @import "code";
+@import "print";
diff --git a/adi_doctools/theme/cosmic/style/collapsible.scss b/adi_doctools/theme/cosmic/style/collapsible.scss
@@ -6,13 +6,52 @@
 
 .collapsible_content {
     overflow: auto;
-    border-top: $border-panel;
     overflow: hidden;
-    height: 0;
     transition: ease opacity .25s;
-    opacity: 0;
 }
 
+@media not print {
+    .collapsible_content {
+        height: 0;
+        opacity: 0;
+    }
+
+    .collapsible {
+        border: $border-panel;
+        margin-bottom: .5em;
+
+        label {
+            padding: 0.75em 1em 0.75em .75em;
+        }
+
+        label .icon {
+            display: block;
+        }
+
+        table.docutils {
+            border: none;
+            width: 100%;
+        }
+    }
+
+    .collapsible_content {
+        border-top: $border-panel;
+    }
+}
+
+@media print {
+    .collapsible {
+        label {
+            padding: 0.5em 0 0.5em 0;
+        }
+
+        label .icon {
+            display: none;
+        }
+    }
+}
+
+
 .collapsible_input:checked ~ label .icon {
     transform: rotate(45deg);
     margin-top: -.5em;
@@ -24,17 +63,10 @@
 }
 
 .collapsible {
-    border: $border-panel;
     border-radius: .25em;
-    margin-bottom: .5em;
-
-    .collapsible {
-        margin: .25em;
-    }
 
     label {
         width: 100%;
-        padding: 0.75em 1em 0.75em .75em;
         user-select: none;
         box-sizing: border-box;
         cursor: pointer;
@@ -46,7 +78,6 @@
     label .icon {
         border: 1px solid var(--text-color1);
         border-width: 0 2px 2px 0;
-        display: block;
         transition: transform ease .125s, margin-top ease .125s;
         width: .6em;
         height: .6em;
@@ -72,11 +103,6 @@
         font-weight: 600;
     }
 
-    table.docutils {
-        border: none;
-        width: 100%;
-    }
-
     .container > p {
         margin-left: .5em;
         margin-right: .5em;

diff --git a/adi_doctools/theme/cosmic/style/element.scss b/adi_doctools/theme/cosmic/style/element.scss
@@ -122,7 +122,7 @@ img {
     max-width: 100%;
 }
 
-@media (min-width: $width-narrow) {
+@media (min-width: $width-content) {
     .body img {
         display: block;
         margin: 0 auto;
@@ -192,6 +192,12 @@ iframe {
     border: none;
 }
 
+@media screen {
+    .iframe-video p, .embed-video p {
+        text-align: center;
+    }
+}
+
 .iframe-video {
     iframe {
         box-shadow: $box-shadow-raised;

diff --git a/adi_doctools/theme/cosmic/style/footer.scss b/adi_doctools/theme/cosmic/style/footer.scss
@@ -1,9 +1,13 @@
 footer {
-    background: var(--bg-color1);
     border-top: $border-panel;
     padding: 1em;
 }
 
+@media screen {
+    footer {
+        background: var(--bg-color1);
+    }
+}
 
 @media (min-width: $width-narrow) {
     footer {

diff --git a/adi_doctools/theme/cosmic/style/header.scss b/adi_doctools/theme/cosmic/style/header.scss
@@ -25,7 +25,6 @@ header {
     z-index: 7;
     position: sticky;
     width: 100%;
-    border-bottom: $border-panel;
     top: 0;
 
     label, button {
@@ -80,6 +79,12 @@ header {
     }
 }
 
+@media screen {
+    header {
+        border-bottom: $border-panel;
+    }
+}
+
 .repotoc-tree.overlay {
     position: sticky;
     top: 3.5rem;
@@ -151,11 +156,23 @@ header {
 }
 
 @media (max-width: $width-narrow) {
+    @media screen {
+        header {
+            border-bottom: $border-panel;
+        }
+    }
+
     header {
         display: flex;
         width: 100%;
-        border-bottom: $border-panel;
-        background: var(--bg-color1-faded1);
+    }
+}
+
+@media screen {
+    @media (max-width: $width-narrow) {
+        header {
+            background: var(--bg-color1-faded1);
+        }
     }
 }
 

diff --git a/adi_doctools/theme/cosmic/style/mixin_admonition.scss b/adi_doctools/theme/cosmic/style/mixin_admonition.scss
@@ -10,8 +10,9 @@ $admonitions: (
     "tip":             #00c852 "info",
     "important":       #00bfa5 "flame",
     "note":            #00b0ff "pencil",
+    "video":           #00b0ff "video",
     "seealso":         #448aff "info",
-    "admonition-todo": #808080 "pencil"
+    "admonition-todo": #808080 "pencil",
 );
 
 @mixin default-admonition($color, $icon-name) {

diff --git a/adi_doctools/theme/cosmic/style/mixin_icons.scss b/adi_doctools/theme/cosmic/style/mixin_icons.scss
@@ -29,6 +29,8 @@ $icons: (
   // Custom icons
   "adi":
     url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M 4,20 V 4 H 19.9191 V 20 Z M 7.27826,6.49579 v 11.480597 l 9.9764,-5.868477 z"/></svg>'),
+  "video":
+    url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M 2,0 V 24 L 22.785156,12 Z"/></svg>'),
   "ez":
     url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m 5.018,3.999805 2.9857,1.67198 -0.38259,0.12626 c -0.52504,0.17328 -1.07049,0.66411 -1.3392,1.20509 -0.21723,0.43733 -0.22466,0.52591 -0.22466,2.67714 0,1.9911 0.0186,2.25967 0.17685,2.55622 0.33368,0.62518 0.60662,0.90561 1.13162,1.16268 0.43986,0.21538 0.65048,0.25744 1.28912,0.25744 h 0.76335 v 1.17569 c 0,0.64662 0.0259,1.24307 0.0575,1.32544 0.0316,0.0824 0.15482,0.14975 0.27381,0.14975 0.16824,0 0.43438,-0.29417 1.19697,-1.32305 l 0.98063,-1.32305 0.6044,-0.002 c 0.33242,-10e-4 0.76943,-0.0518 0.97113,-0.11227 0.51944,-0.15563 1.11066,-0.69784 1.37134,-1.25764 0.19223,-0.41283 0.22301,-0.62509 0.2238,-1.54373 4.8e-4,-0.5858 0.0209,-1.0755 0.0392,-1.06509 l 3.76425,2.1446 -13.88154,8.17493 z m 4.96824,10.1933 v -1.10454 H 9.00372 c -0.645,0 -1.09561,-0.0472 -1.31172,-0.13755 -0.38773,-0.162 -0.89188,-0.70517 -0.99433,-1.07129 -0.0398,-0.14224 -0.0724,-1.17459 -0.0724,-2.29412 0,-2.03183 4.8e-4,-2.03627 0.25107,-2.46256 0.34735,-0.5908 0.83662,-0.85105 1.6,-0.85105 0.58577,0 0.62661,0.0179 2.78,1.22032 1.20203,0.67117 2.41982,1.34968 2.70621,1.50779 l 0.52071,0.28749 0.0265,1.19398 c 0.0322,1.44936 -0.10361,1.86769 -0.74421,2.29242 -0.34684,0.22996 -0.52287,0.27384 -1.26196,0.31457 l -0.8589,0.0473 -0.76248,1.01409 c -0.41936,0.55776 -0.79252,1.04415 -0.82925,1.08087 -0.0367,0.0367 -0.0668,-0.43027 -0.0668,-1.03776 z m 4.80473,-5.32892 c -0.23381,-0.12276 -0.26035,-0.18758 -0.26035,-0.6358 0,-0.64661 -0.34513,-1.35097 -0.81944,-1.67237 -0.33149,-0.22462 -0.43408,-0.23909 -2.01345,-0.28402 -1.64292,-0.0467 -1.67019,-0.051 -2.13753,-0.33136 l -0.47337,-0.28402 1.93335,-0.0257 c 2.21309,-0.0294 2.66071,0.0504 3.28653,0.58612 0.52719,0.45125 0.77295,1.05819 0.79972,1.97499 0.0118,0.40328 0.004,0.75025 -0.0168,0.77104 -0.021,0.0208 -0.15541,-0.0237 -0.29861,-0.0989 z"/></svg>'),
   "external":

diff --git a/adi_doctools/theme/cosmic/style/print.scss b/adi_doctools/theme/cosmic/style/print.scss
@@ -0,0 +1,25 @@
+@media not print {
+    .only-print {
+        display: none !important;
+    }
+}
+
+@media print {
+    .only-screen {
+        display: none !important;
+    }
+
+    header #left, header .reverse {
+        display: none !important;
+    }
+
+    body.light .highlight {
+        background: none;
+        border: 1px solid var(--text-color3);
+    }
+
+    .body {
+        padding: 0;
+    }
+
+}
diff --git a/adi_doctools/theme/cosmic/style/style.scss b/adi_doctools/theme/cosmic/style/style.scss
@@ -81,11 +81,16 @@ body.dark {
 
 body {
     margin: 0;
-    background-color: var(--bg-color1);
     color: var(--text-color1);
     overflow-x: hidden;
 }
 
+@media screen {
+    body {
+        background-color: var(--bg-color1);
+    }
+}
+
 * {
     box-sizing: border-box;
 }
@@ -158,7 +163,7 @@ svg {
     margin: 0 auto;
 }
 
-@media (min-width: $width-narrow) {
+@media (min-width: $width-content) {
     #hdl-component-diagram svg {
         float: right;
         margin: -3em 0 0 1em;

diff --git a/adi_doctools/theme/cosmic/style/variable.scss b/adi_doctools/theme/cosmic/style/variable.scss
@@ -26,4 +26,5 @@ $border-radius: .25em;
 
 $width-wide: 105em;
 $width-narrow: 85em;
+$width-content: 60em;
 $width-narrowest: 40em;
diff --git a/docs/docs_guidelines.rst b/docs/docs_guidelines.rst
@@ -745,26 +745,39 @@ The directive syntax is:
 
    .. video:: <url>
 
+      <caption>
+
+Always add a caption to the video, since a PDF output won't contain the embed
+video, but a link to it.
+
 For example:
 
 .. code:: rst
 
    .. video:: http://ftp.fau.de/fosdem/2015/devroom-software_defined_radio/iiosdr.mp4
 
+      **Linux Industrial IO framework** - Lars-Peter Clausen, Analog Devices Inc
+
 Renders as:
 
 .. video:: http://ftp.fau.de/fosdem/2015/devroom-software_defined_radio/iiosdr.mp4
 
+   **Linux Industrial IO framework** - Lars-Peter Clausen, Analog Devices Inc
+
 And:
 
 .. code:: rst
 
    .. video:: https://www.youtube.com/watch?v=p_VntEwUe24
 
+      **LibIIO - A Library for Interfacing with Linux IIO Devices** - Dan Nechita, Analog Devices Inc
+
 Renders as:
 
 .. video:: https://www.youtube.com/watch?v=p_VntEwUe24
 
+   **LibIIO - A Library for Interfacing with Linux IIO Devices** - Dan Nechita, Analog Devices Inc
+
 ESD warning directive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~