Update documentation framework

ubuntu · Nov 3, 2023 · 33729da · 33729da
1 parent b6b57e6
commit 33729da
Show file tree

Hide file tree

Showing 12 changed files with 346 additions and 259 deletions.
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
@@ -0,0 +1,98 @@
+Acknowledgements
+adml
+ADML
+admx
+ADMX
+adsys
+ADSys
+adsysctl
+adsysd
+adwatchd
+apparmor
+AppArmor
+AppArmor's
+autocompletion
+autoenroll
+autoenrollment
+autoload
+backend
+backends
+CAs
+CEP
+CES
+changelog
+compinit
+config
+constructiveCAs
+CSR
+dconf
+dir
+Dropdown
+enrolment
+erroring
+executables
+fpath
+FQDN
+GDM
+GPL
+GPO
+gpolist
+GPOs
+GPT
+GSettings
+GVfs
+html
+https
+idempotency
+IIS
+incrementation
+incrementing
+infos
+ini
+ip
+Jira
+kerberos
+Kerberos
+LDAP
+lifecycle
+LTS
+MacOS
+macOS
+multiline
+OpenLDAP
+OU
+OUs
+polkit
+powershell
+PowerShell
+readthedocs
+runscripts
+sss
+sssd
+SSSD
+subcommands
+subdirectory
+subprofile
+subprofiles
+sudo
+syntaxes
+systemd
+systemd's
+sysvol
+TDB
+TODO
+toolset
+Transactional
+txt
+ubuntu
+Unix
+unmonitoring
+unmount
+unmounting
+Unmounting
+unticking
+vendoring
+Winbind
+yaml
+zsh
+zshrc
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,7 +1,8 @@
 /*env*/
-.sphinx/venv
+.sphinx/venv/
 .sphinx/warnings.txt
 .sphinx/.wordlist.dic
+.sphinx/.doctrees/
 _build
 .DS_Store
 __pycache__

diff --git a/docs/.sphinx/_static/furo_colors.css b/docs/.sphinx/_static/furo_colors.css
@@ -0,0 +1,88 @@
+body {
+    --color-code-background: #f8f8f8;
+    --color-code-foreground: black;
+    --font-stack: Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+    --font-stack--monospace: Ubuntu Mono, Consolas, Monaco, Courier, monospace;
+    --color-foreground-primary: #111;
+    --color-foreground-secondary: var(--color-foreground-primary);
+    --color-foreground-muted: #333;
+    --color-background-secondary: #FFF;
+    --color-background-hover: #f2f2f2;
+    --color-brand-primary: #111;
+    --color-brand-content: #06C;
+    --color-api-background: #cdcdcd;
+    --color-inline-code-background: rgba(0,0,0,.03);
+    --color-sidebar-link-text: #111;
+    --color-sidebar-item-background--current: #ebebeb;
+    --color-sidebar-item-background--hover: #f2f2f2;
+    --toc-font-size: var(--font-size--small);
+    --color-admonition-title-background--note: var(--color-background-primary);
+    --color-admonition-title-background--tip: var(--color-background-primary);
+    --color-admonition-title-background--important: var(--color-background-primary);
+    --color-admonition-title-background--caution: var(--color-background-primary);
+    --color-admonition-title--note: #24598F;
+    --color-admonition-title--tip: #24598F;
+    --color-admonition-title--important: #C7162B;
+    --color-admonition-title--caution: #F99B11;
+    --color-highlighted-background: #EbEbEb;
+    --color-link-underline: var(--color-background-primary);
+    --color-link-underline--hover: var(--color-background-primary);
+    --color-version-popup: #772953;
+}
+
+@media not print {
+    body[data-theme="dark"] {
+        --color-code-background: #202020;
+        --color-code-foreground: #d0d0d0;
+        --color-foreground-secondary: var(--color-foreground-primary);
+        --color-foreground-muted: #CDCDCD;
+        --color-background-secondary: var(--color-background-primary);
+        --color-background-hover: #666;
+        --color-brand-primary: #fff;
+        --color-brand-content: #06C;
+        --color-sidebar-link-text: #f7f7f7;
+        --color-sidebar-item-background--current: #666;
+        --color-sidebar-item-background--hover: #333;
+        --color-admonition-background: transparent;
+        --color-admonition-title-background--note: var(--color-background-primary);
+        --color-admonition-title-background--tip: var(--color-background-primary);
+        --color-admonition-title-background--important: var(--color-background-primary);
+        --color-admonition-title-background--caution: var(--color-background-primary);
+        --color-admonition-title--note: #24598F;
+        --color-admonition-title--tip: #24598F;
+        --color-admonition-title--important: #C7162B;
+        --color-admonition-title--caution: #F99B11;
+        --color-highlighted-background: #666;
+        --color-link-underline: var(--color-background-primary);
+        --color-link-underline--hover: var(--color-background-primary);
+        --color-version-popup: #F29879;
+    }
+    @media (prefers-color-scheme: dark) {
+        body:not([data-theme="light"]) {
+            --color-code-background: #202020;
+            --color-code-foreground: #d0d0d0;
+            --color-foreground-secondary: var(--color-foreground-primary);
+            --color-foreground-muted: #CDCDCD;
+            --color-background-secondary: var(--color-background-primary);
+            --color-background-hover: #666;
+            --color-brand-primary: #fff;
+            --color-brand-content: #06C;
+            --color-sidebar-link-text: #f7f7f7;
+            --color-sidebar-item-background--current: #666;
+            --color-sidebar-item-background--hover: #333;
+            --color-admonition-background: transparent;
+            --color-admonition-title-background--note: var(--color-background-primary);
+            --color-admonition-title-background--tip: var(--color-background-primary);
+            --color-admonition-title-background--important: var(--color-background-primary);
+            --color-admonition-title-background--caution: var(--color-background-primary);
+            --color-admonition-title--note: #24598F;
+            --color-admonition-title--tip: #24598F;
+            --color-admonition-title--important: #C7162B;
+            --color-admonition-title--caution: #F99B11;
+            --color-highlighted-background: #666;
+            --color-link-underline: var(--color-background-primary);
+            --color-link-underline--hover: var(--color-background-primary);
+            --color-version-popup: #F29879;
+        }
+    }
+}
diff --git a/docs/.sphinx/_static/github_issue_links.js b/docs/.sphinx/_static/github_issue_links.js
@@ -1,4 +1,12 @@
+// if we already have an onload function, save that one
+var prev_handler = window.onload;
+
 window.onload = function() {
+    // call the previous onload function
+    if (prev_handler) {
+        prev_handler();
+    }
+
     const link = document.createElement("a");
     link.classList.add("muted-link");
     link.classList.add("github-issue-link");

diff --git a/docs/.sphinx/_templates/base.html b/docs/.sphinx/_templates/base.html
@@ -5,3 +5,8 @@
   const github_url = "{{ github_url }}";
 </script>
 {% endblock theme_scripts %}
+
+{# ru-fu: don't include the color variables from the conf.py file, but use a
+   separate CSS file to save space #}
+{% block theme_styles %}
+{% endblock theme_styles %}
diff --git a/docs/.sphinx/_templates/footer.html b/docs/.sphinx/_templates/footer.html
@@ -1,31 +1,40 @@
-{# ru-fu: copied from Furo, with modifications as stated below #}
+{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #}
 
 <div class="related-pages">
-  {% if next -%}
-    <a class="next-page" href="{{ next.link }}">
-      <div class="page-info">
-        <div class="context">
-          <span>{{ _("Next") }}</span>
+  {# mod: Per-page navigation #}
+  {% if meta %}
+    {% if 'sequential_nav' in meta %}
+      {% set sequential_nav = meta.sequential_nav %}
+    {% endif %}  
+  {% endif %}
+  {# mod: Conditional wrappers to control page navigation buttons #}
+  {% if sequential_nav != "none" -%}
+    {% if next and (sequential_nav == "next" or sequential_nav == "both") -%}
+      <a class="next-page" href="{{ next.link }}">
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Next") }}</span>
+          </div>
+          <div class="title">{{ next.title }}</div>
         </div>
-        <div class="title">{{ next.title }}</div>
-      </div>
-      <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
-    </a>
-  {%- endif %}
-  {% if prev -%}
-    <a class="prev-page" href="{{ prev.link }}">
-      <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
-      <div class="page-info">
-        <div class="context">
-          <span>{{ _("Previous") }}</span>
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+      </a>
+    {%- endif %}
+    {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%}
+      <a class="prev-page" href="{{ prev.link }}">
+        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+        <div class="page-info">
+          <div class="context">
+            <span>{{ _("Previous") }}</span>
+          </div>
+          {% if prev.link == pathto(master_doc) %}
+            <div class="title">{{ _("Home") }}</div>
+          {% else %}
+            <div class="title">{{ prev.title }}</div>
+          {% endif %}
         </div>
-        {% if prev.link == pathto(master_doc) %}
-        <div class="title">{{ _("Home") }}</div>
-        {% else %}
-        <div class="title">{{ prev.title }}</div>
-        {% endif %}
-      </div>
-    </a>
+      </a>
+    {%- endif %}
   {%- endif %}
 </div>
 <div class="bottom-of-page">
@@ -44,7 +53,7 @@
     </div>
     {%- endif %}
 
-    {# ru-fu: removed "Made with" #}
+    {# mod: removed "Made with" #}
 
     {%- if last_updated -%}
     <div class="last-updated">
@@ -63,7 +72,7 @@
   </div>
   <div class="right-details">
 
-    {# ru-fu: replaced RTD icons with our links #}
+    {# mod: replaced RTD icons with our links #}
 
     {% if discourse %}
     <div class="ask-discourse">

diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
@@ -1,13 +1,14 @@
+furo
+linkify-it-py
+lxd-sphinx-extensions
+myst-parser
+pyspelling
 sphinx
 sphinx-autobuild
+sphinx-copybutton
 sphinx-design
-furo
-sphinx-tabs
+sphinx-notfound-page
 sphinx-reredirects
-pyspelling
-sphinxext-opengraph
-lxd-sphinx-extensions
-sphinx-copybutton
-myst-parser
+sphinx-tabs
 sphinxcontrib-jquery
-sphinx-notfound-page
+sphinxext-opengraph
diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml
@@ -2,10 +2,11 @@ matrix:
 - name: rST files
   aspell:
     lang: en
-    d: en_US
+    d: en_GB
   dictionary:
     wordlists:
     - .wordlist.txt
+    - .custom_wordlist.txt
     output: .sphinx/.wordlist.dic
   sources:
   - _build/**/*.html
@@ -22,6 +23,7 @@ matrix:
       - link
       - title
       - div.relatedlinks
+      - strong.command
       - div.visually-hidden
       - img
       - a.p-navigation__link