docs: updated sphinx doc starter pack (#1041)

Updated to tip of main. Disabled some links that don't exist for adsys. Fixes to the title so it fits the width of the left menu and fixed address of the documentation site for ogp.
ubuntu · Jul 5, 2024 · b8235da · b8235da
2 parents a98208e + 379e483
commit b8235da
Show file tree

Hide file tree

Showing 24 changed files with 870 additions and 174 deletions.
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
@@ -65,6 +65,7 @@ kerberos
 Kerberos
 krb
 LDAP
+libkrb
 lifecycle
 linux
 localhost

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,9 +1,15 @@
 /*env*/
 .sphinx/venv/
+.sphinx/requirements.txt
 .sphinx/warnings.txt
 .sphinx/.wordlist.dic
 .sphinx/.doctrees/
+.sphinx/node_modules/
+package*.json
 _build
 .DS_Store
 __pycache__
 .idea/
+.vscode/
+.sphinx/styles/*
+.sphinx/vale.ini
diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
@@ -10,6 +10,10 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    pre_install:
+      - python3 docs/.sphinx/build_requirements.py
+      - git fetch --unshallow || true
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

diff --git a/docs/.sphinx/_static/404.svg b/docs/.sphinx/_static/404.svg
diff --git a/docs/.sphinx/_static/custom.css b/docs/.sphinx/_static/custom.css
@@ -1,18 +1,129 @@
-/** Fix the font weight (300 for normal, 400 for slightly bold) **/
-
-div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
-    font-weight: 300
+/**
+    Ubuntu variable font definitions.
+    Based on https://github.com/canonical/vanilla-framework/blob/main/scss/_base_fontfaces.scss
+
+    When font files are updated in Vanilla, the links to font files will need to be updated here as well.
+*/
+
+/* default font set */
+@font-face {
+  font-family: 'Ubuntu variable';
+  font-stretch: 100%; /*  min and max value for the width axis, expressed as percentage */
+  font-style: normal;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/f1ea362b-Ubuntu%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations');
+}
+
+@font-face {
+  font-family: 'Ubuntu variable';
+  font-stretch: 100%; /*  min and max value for the width axis, expressed as percentage */
+  font-style: italic;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/90b59210-Ubuntu-Italic%5Bwdth,wght%5D-latin-v0.896a.woff2') format('woff2-variations');
+}
+
+@font-face {
+  font-family: 'Ubuntu Mono variable';
+  font-style: normal;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/d5fc1819-UbuntuMono%5Bwght%5D-latin-v0.869.woff2') format('woff2-variations');
+}
+
+/* cyrillic-ext */
+@font-face {
+  font-family: 'Ubuntu variable';
+  font-stretch: 100%; /*  min and max value for the width axis, expressed as percentage */
+  font-style: normal;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/77cd6650-Ubuntu%5Bwdth,wght%5D-cyrillic-extended-v0.896a.woff2') format('woff2-variations');
+  unicode-range: U+0460-052F, U+20B4, U+2DE0-2DFF, U+A640-A69F;
+}
+
+/* cyrillic */
+@font-face {
+  font-family: 'Ubuntu variable';
+  font-stretch: 100%; /*  min and max value for the width axis, expressed as percentage */
+  font-style: normal;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/2702fce5-Ubuntu%5Bwdth,wght%5D-cyrillic-v0.896a.woff2') format('woff2-variations');
+  unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+
+/* greek-ext */
+@font-face {
+  font-family: 'Ubuntu variable';
+  font-stretch: 100%; /*  min and max value for the width axis, expressed as percentage */
+  font-style: normal;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/5c108b7d-Ubuntu%5Bwdth,wght%5D-greek-extended-v0.896a.woff2') format('woff2-variations');
+  unicode-range: U+1F00-1FFF;
+}
+
+/* greek */
+@font-face {
+  font-family: 'Ubuntu variable';
+  font-stretch: 100%; /*  min and max value for the width axis, expressed as percentage */
+  font-style: normal;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/0a14c405-Ubuntu%5Bwdth,wght%5D-greek-v0.896a.woff2') format('woff2-variations');
+  unicode-range: U+0370-03FF;
+}
+
+/* latin-ext */
+@font-face {
+  font-family: 'Ubuntu variable';
+  font-stretch: 100%; /*  min and max value for the width axis, expressed as percentage */
+  font-style: normal;
+  font-weight: 100 800; /*  min and max value for the weight axis */
+  src: url('https://assets.ubuntu.com/v1/19f68eeb-Ubuntu%5Bwdth,wght%5D-latin-extended-v0.896a.woff2') format('woff2-variations');
+  unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
+}
+
+
+/** Define font-weights as per Vanilla
+    Based on: https://github.com/canonical/vanilla-framework/blob/main/scss/_base_typography-definitions.scss
+
+    regular text: 400,
+    bold: 550,
+    thin: 300,
+
+    h1: bold,
+    h2: 180;
+    h3: bold,
+    h4: 275,
+    h5: bold,
+    h6: regular
+*/
+
+/* default regular text */
+html {
+    font-weight: 400;
 }
 
-.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
-    font-weight: 400;
+/* heading specific definitions */
+h1, h3, h5 { font-weight: 550; }
+h2 { font-weight: 180; }
+h4 { font-weight: 275; }
+
+/* bold */
+.toc-tree li.scroll-current>.reference,
+dl.glossary dt,
+dl.simple dt,
+dl:not([class]) dt {
+    font-weight: 550;
 }
 
+
 /** Table styling **/
 
 th.head {
     text-transform: uppercase;
     font-size: var(--font-size--small);
+    text-align: initial;
+}
+
+table.align-center th.head {
+    text-align: center
 }
 
 table.docutils {
@@ -57,34 +168,63 @@ a.headerlink {
     border-left: 2px solid var(--color-brand-primary);
 }
 
-/** Some tweaks for issue #16 **/
+/** Some tweaks for Sphinx tabs **/
 
 [role="tablist"] {
     border-bottom: 1px solid var(--color-sidebar-item-background--hover);
 }
 
-.sphinx-tabs-tab[aria-selected="true"] {
+.sphinx-tabs-tab[aria-selected="true"],  .sd-tab-set>input:checked+label{
     border: 0;
     border-bottom: 2px solid var(--color-brand-primary);
-    background-color: var(--color-sidebar-item-background--current);
-    font-weight:300;
+    font-weight: 400;
+    font-size: 1rem;
+    color: var(--color-brand-primary);
+}
+
+body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] {
+    background: var(--color-background-primary);
+    border-bottom: 2px solid var(--color-brand-primary);
+}
+
+button.sphinx-tabs-tab[aria-selected="false"]:hover, .sd-tab-set>input:not(:checked)+label:hover {
+    border-bottom: 2px solid var(--color-foreground-border);
+}
+
+button.sphinx-tabs-tab[aria-selected="false"]{
+    border-bottom: 2px solid var(--color-background-primary);
+}
+
+body[data-theme="dark"] .sphinx-tabs-tab {
+    background: var(--color-background-primary);
 }
 
-.sphinx-tabs-tab{
+.sphinx-tabs-tab, .sd-tab-set>label{
     color: var(--color-brand-primary);
-    font-weight:300;
+    font-family: var(--font-stack);
+    font-weight: 400;
+    font-size: 1rem;
+    padding: 1em 1.25em .5em
 }
 
 .sphinx-tabs-panel {
     border: 0;
     border-bottom: 1px solid var(--color-sidebar-item-background--hover);
     background: var(--color-background-primary);
+    padding: 0.75rem 0 0.75rem 0;
 }
 
-button.sphinx-tabs-tab:hover {
-    background-color: var(--color-sidebar-item-background--hover);
+body[data-theme="dark"] .sphinx-tabs-panel {
+    background: var(--color-background-primary);
 }
 
+/** A tweak for issue #190 **/
+
+.highlight .hll {
+    background-color: var(--color-highlighted-background);
+}
+
+
 /** Custom classes to fix scrolling in tables by decreasing the
     font size or breaking certain columns.
     Specify the classes in the Markdown file with, for example:
@@ -157,6 +297,15 @@ button.version_select {
 
 .available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
 
+/** Suppress link underlines outside on-hover **/
+a {
+    text-decoration: none;
+}
+
+a:hover, a:visited:hover {
+    text-decoration: underline;
+}
+
 .show {display:block;}
 
 /** Fix for nested numbered list - the nested list is lettered **/
@@ -187,3 +336,43 @@ details summary {
     color: var(--color-version-popup);
     font-weight: bolder;
 }
+
+/* Code-block copybutton invisible by default
+   (overriding Furo config to achieve default copybutton setting). */
+.highlight button.copybtn {
+   opacity: 0;
+}
+
+/* Mimicking the 'Give feedback' button for UX consistency */
+.sidebar-search-container input[type=submit] {
+    color: #FFFFFF;
+    border: 2px solid #D6410D;
+    padding: var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal);
+    background: #D6410D;
+    font-weight: bold;
+    font-size: var(--font-size--small);
+    cursor: pointer;
+}
+
+.sidebar-search-container input[type=submit]:hover {
+    text-decoration: underline;
+}
+
+/* Make inline code the same size as code blocks */
+p code.literal {
+    border: 0;
+    font-size: var(--code-font-size);
+}
+
+/* Use the general admonition font size for inline code */
+.admonition p code.literal {
+    font-size: var(--admonition-font-size);
+}
+
+.highlight .s, .highlight .s1, .highlight .s2 {
+    color: #3F8100;
+}
+
+.highlight .o {
+    color: #BB5400;
+}
diff --git a/docs/.sphinx/_static/footer.css b/docs/.sphinx/_static/footer.css
@@ -0,0 +1,47 @@
+.display-contributors {
+  color: var(--color-sidebar-link-text);
+  cursor: pointer;
+}
+.all-contributors {
+  display: none;
+  z-index: 55;
+  list-style: none;
+  position: fixed;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  width: 200px;
+  height: 200px;
+  overflow-y: scroll;
+  margin: auto;
+  padding: 0;
+  background: var(--color-background-primary);
+    scrollbar-color: var(--color-foreground-border) transparent;
+    scrollbar-width: thin;
+}
+
+.all-contributors li:hover {
+  background: var(--color-sidebar-item-background--hover);
+  width: 100%;
+}
+
+.all-contributors li a{
+  color: var(--color-sidebar-link-text);
+  padding: 1rem;
+  display: inline-block;
+}
+
+#overlay {
+  position: fixed;
+  display: none;
+  width: 100%;
+  height: 100%; 
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background-color: rgba(0,0,0,0.5); 
+  z-index: 2; 
+  cursor: pointer; 
+}
diff --git a/docs/.sphinx/_static/footer.js b/docs/.sphinx/_static/footer.js
@@ -0,0 +1,12 @@
+$(document).ready(function() {
+    $(document).on("click", function () {
+        $(".all-contributors").hide();
+        $("#overlay").hide();
+    });
+
+    $('.display-contributors').click(function(event) {
+        $('.all-contributors').toggle();
+        $("#overlay").toggle();
+        event.stopPropagation();
+    });
+})
-Original file line number
+Diff line change
@@ Expand Up / @@ -65,6 +65,7 @@ kerberos @@
     Kerberos
     krb
     LDAP
+    libkrb
     lifecycle
     linux
     localhost
@@ Expand Down @@