Git role, improve breakpoints and overall style

Git role: Fetch default branch from lut.py and add option to create a direct link to the source code/raw file. SASS: Improve CSS breakpoints, overall styles. Signed-off-by: Jorge Marques <[email protected]>
analogdevicesinc · Sep 14, 2024 · 8678e9a · 8678e9a
1 parent 4f5ff84
commit 8678e9a
Show file tree

Hide file tree

Showing 16 changed files with 277 additions and 163 deletions.
diff --git a/.gitignore b/.gitignore
@@ -13,3 +13,4 @@ node_modules
 *.json
 *.woff2
 adi_doctools/theme/*/static/fonts
+.sass-cache
diff --git a/adi_doctools/role/common.py b/adi_doctools/role/common.py
@@ -8,7 +8,8 @@
 dft_url_dokuwiki = 'https://wiki.analog.com'
 dft_url_ez = 'https://ez.analog.com'
 dft_url_mw = 'https://www.mathworks.com'
-dft_url_git = 'https://github.com/analogdevicesinc'
+dft_url_git_gui = 'https://github.com/analogdevicesinc/{repo}/tree'
+dft_url_git_raw = 'https://raw.githubusercontent.com/analogdevicesinc/{repo}'
 dft_url_adi = 'https://www.analog.com'
 dft_url_xilinx = 'https://www.xilinx.com'
 dft_url_intel = 'https://www.intel.com'
@@ -24,7 +25,9 @@
     ['iio-oscilloscope', "IIO Oscilloscope"],
     ['doctools',         "Doctools"],
     ['documentation',    "System Level Documentation"],
-    ['pyadi-iio',        "PyADI-IIO"]
+    ['pyadi-iio',        "PyADI-IIO"],
+    ['meta-adi',         "META-ADI"],
+    ['wiki-scripts',     "Wiki Scripts"]
 ]
 vendors = ['xilinx', 'intel', 'mw']
 
@@ -90,38 +93,47 @@ def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
     return role
 
 
-def get_active_branch_name():
-    try:
-        branch = subprocess.run(['git', 'branch',
-                                 '--show-current'], capture_output=True)
-        return branch.stdout.decode('utf-8').replace('\n', '')
-    except Exception:
-        # Return placeholder is git is unreachable, e.g. container
-        return "<unknown>"
+def get_default_brach(repo, inliner):
+    """
+    Get default branch for each repo.
+    If it is not known, returns 'main'
+    """
+    app = inliner.document.settings.env.app
+    if repo in app.lut['repos']:
+        return app.lut['repos'][repo]['branch']
+    else:
+        return 'main'
 
 
 def git(repo, alt_name):
     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-        url = get_url_config('git', inliner) + '/' + repo
-        if text == '/':
-            name = "ADI " + alt_name + " repository"
-            node = nodes.reference(rawtext, name, refuri=url,
-                                   classes=['icon', 'git'], **options)
+        text, path = get_outer_inner(text)
+
+        pos = path.find('+')
+        if path[0:pos] == "raw":
+            type_ = path[0:pos]
         else:
-            text, path = get_outer_inner(text)
-            pos = path.find(':')
-            if pos in [0, -1]:
-                branch = get_active_branch_name()
-            else:
-                branch = path[0:pos]
-            path = path[pos+1:]
+            type_ = "gui"
+        path = path[pos+1:]
+
+        pos = path.find(':')
+        if pos in [0, -1]:
+            branch = get_default_brach(repo, inliner)
+        else:
+            branch = path[0:pos]
+        path = path[pos+1:]
+        if text is None:
             if path == '/':
-                path = ''
-            if text is None:
+                text = "ADI " + alt_name + " repository"
+            else:
                 text = path
-            url = url + '/tree/' + branch + '/' + path
-            node = nodes.reference(rawtext, text, refuri=url,
-                                   classes=['icon', 'git'], **options)
+        if path == '/':
+            path = ''
+
+        url = get_url_config('git_'+type_, inliner).format(repo=repo)
+        url = url + '/' + branch + '/' + path
+        node = nodes.reference(rawtext, text, refuri=url,
+                               classes=['icon', 'git'], **options)
         return [node], []
 
     return role
@@ -167,7 +179,8 @@ def common_setup(app):
     app.add_config_value('url_dokuwiki',  dft_url_dokuwiki,  'env')
     app.add_config_value('url_ez',        dft_url_ez,        'env')
     app.add_config_value('url_mw',        dft_url_mw,        'env')
-    app.add_config_value('url_git',       dft_url_git,       'env')
+    app.add_config_value('url_git_gui',   dft_url_git_gui,   'env')
+    app.add_config_value('url_git_raw',   dft_url_git_raw,   'env')
     app.add_config_value('url_adi',       dft_url_adi,       'env')
     app.add_config_value('url_xilinx',    dft_url_xilinx,    'env')
     app.add_config_value('url_intel',     dft_url_intel,     'env')
diff --git a/adi_doctools/role/interref.py b/adi_doctools/role/interref.py
@@ -408,7 +408,7 @@ def resolve_reference_in_inventory(env: BuildEnvironment,
 class IntersphinxDispatcher(CustomReSTDispatcher):
     """Custom dispatcher for ref role.
 
-    This enables :ref+***: roles on parsing reST document.
+    This enables :ref-***: roles on parsing reST document.
     """
 
     def role(

diff --git a/adi_doctools/theme/cosmic/style/admonition.scss b/adi_doctools/theme/cosmic/style/admonition.scss
@@ -3,12 +3,12 @@
 /* Inspired by: https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/content/_admonitions.sass */
 
 .admonition, .topic {
-    margin: 1rem auto;
-    padding: 0 0 0.5rem 0;
+    margin: 0 auto .5em auto;
+    padding: 0 0 0.5em 0;
 
     background: var(--color-admonition-background);
 
-    border-radius: 0.2rem;
+    border-radius: $border-radius;
 
     overflow: hidden;
     page-break-inside: avoid;
@@ -26,9 +26,9 @@ p.topic-title {
     margin: 0;
     position: relative;
     margin-top: 0;
-    padding-left: 2rem;
-    padding-top: .4rem;
-    padding-bottom: .4rem;
+    padding-left: 2em;
+    padding-top: .4em;
+    padding-bottom: .4em;
 
     font-weight: 500;
     line-height: 1.3;
@@ -37,10 +37,10 @@ p.topic-title {
     &::before {
         content: "";
         position: absolute;
-        left: .5rem;
-        top: .5rem;
-        width: 1rem;
-        height: 1rem;
+        left: .5em;
+        top: .5em;
+        width: 1em;
+        height: 1em;
     }
 }
 
@@ -69,7 +69,7 @@ p.topic-title {
 
 .admonition p {
     margin: 0;
-    padding: 0 .5rem;
+    padding: 0 .5em;
 }
 
 /* Variants */

diff --git a/adi_doctools/theme/cosmic/style/collapsible.scss b/adi_doctools/theme/cosmic/style/collapsible.scss
@@ -63,7 +63,7 @@
 }
 
 .collapsible {
-    border-radius: .25em;
+    border-radius: $border-radius;
 
     label {
         width: 100%;

diff --git a/adi_doctools/theme/cosmic/style/element.scss b/adi_doctools/theme/cosmic/style/element.scss
@@ -9,23 +9,6 @@ a, input, textarea, select, button, summary, label {
     -webkit-tap-highlight-color: transparent;
 }
 
-a {
-    user-select: none;
-    text-decoration: none;
-    color: inherit;
-}
-
-.body {
-    p a, a.reference.internal:not(.image-reference), aside a {
-        color: var(--accent-color);
-        border-bottom: 1px solid rgba(125, 125, 125, .25);
-    }
-
-    p a:hover, a.reference.internal:hover, aside a:hover {
-        border-color: var(--text-color2);
-    }
-}
-
 video {
     max-width: 100%;
 }
@@ -54,7 +37,7 @@ code.literal {
     border: 1px solid rgba(125, 125, 125, 0.15);
     background: rgba(125, 125, 125, 0.05);
     border-radius: $border-radius;
-    padding: .1em .2em;
+    padding: 0em .2em 0.1em .2em;
     font-size: 1.1em;
 }
 
@@ -64,6 +47,7 @@ a {
 
 .highlight {
     padding: .75em;
+    margin-bottom: .5em;
     border-radius: $border-radius;
     overflow-x: auto;
 }
@@ -81,6 +65,10 @@ a {
     overflow-x: auto;
 }
 
+.table-wrapper {
+    margin-bottom: .5em;
+}
+
 table.docutils {
     border-spacing: 0;
     border-radius: $border-radius;
@@ -122,7 +110,13 @@ img {
     max-width: 100%;
 }
 
-@media (min-width: $width-content) {
+@media print {
+    img {
+        break-inside: avoid;
+    }
+}
+
+@media (min-width: $screen-1) {
     .body img {
         display: block;
         margin: 0 auto;
@@ -159,10 +153,12 @@ body.dark .body img {
 }
 
 table.regmap {
-    font-size: 0.8rem;
+    td.description {
+        font-size: 0.8em;
+    }
 
-    .pre {
-        line-height: 1.8em;
+    td:not(.description) code.literal {
+        font-size: 1em;
     }
 }
 
@@ -210,7 +206,7 @@ iframe {
     }
 }
 
-@media (max-width: $width-narrow) {
+@media (max-width: $screen-1) {
     .iframe-video {
         width: 100%;
         overflow: hidden;
@@ -240,13 +236,13 @@ iframe {
     }
 }
 
-@media (min-width: $width-narrowest) {
+@media (min-width: $screen-0) {
     .esd-warning {
         display: flex;
     }
 }
 
-@media (max-width: $width-narrowest) {
+@media (max-width: $screen-0) {
     .esd-warning .icon {
         margin: 0 auto;
     }

diff --git a/adi_doctools/theme/cosmic/style/footer.scss b/adi_doctools/theme/cosmic/style/footer.scss
@@ -9,13 +9,19 @@ footer {
     }
 }
 
-@media (min-width: $width-narrow) {
+@media (min-width: $screen-1) and (max-width: $screen-2) {
+    footer {
+        margin-left: 18rem;
+    }
+}
+
+@media (min-width: $screen-2) {
     footer {
         margin-left: calc(40vw - 14em);
     }
 }
 
-@media (min-width: $width-wide) {
+@media (min-width: $screen-3) {
     footer {
         max-width: 60rem;
     }
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,3 +13,4 @@ node_modules @@
     *.json
     *.woff2
     adi_doctools/theme/*/static/fonts
+    .sass-cache