docs: Cosmetic improvements and styling (#2057)

Make the docs look more like the documentation produced on Ubuntu.com.

Make the default font size larger for accessibility.

Code literals are now the same size as regular font for the same reason,
but made slightly bolded to help pick them out from text (which should
help e.g. when commands are included as inline text and not a code block.

Give the sidebar headings a higher weight, for easier navigation.

For accessibility, change the weight and spacing between topics in the
side bars to help separate them and make it easier to tell where one link
ends and the next begins.

2 files changed, 285 insertions, 5 deletions

diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index a4103a7e..c8d460ab 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -1,3 +1,4 @@
+import datetime
 import os
 import sys
 
@@ -18,7 +19,7 @@ sys.path.insert(0, os.path.abspath("."))
 
 # General information about the project.
 project = "cloud-init"
-copyright = "Canonical Ltd."
+copyright = f"Canonical Group Ltd, {datetime.date.today().year}"
 
 # -- General configuration ----------------------------------------------------
 
@@ -71,15 +72,46 @@ copybutton_only_copy_prompt_lines = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "furo"
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-html_static_path = ["static"]
 html_theme_options = {
     "light_logo": "logo.png",
     "dark_logo": "logo-dark-mode.png",
+    "light_css_variables": {
+        "font-stack": "Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif",
+        "font-stack--monospace": "Ubuntu Mono variable, 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-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",
+        "sidebar-item-line-height": "1.3rem",
+        "color-link-underline": "var(--color-background-primary)",
+        "color-link-underline--hover": "var(--color-background-primary)",
+    },
+    "dark_css_variables": {
+        "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",
+    },
 }
 
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_static_path = ["static"]
+html_css_files = ["css/custom.css"]
+
 html_extra_path = ["googleaf254801a5285c31.html"]
 
 # Make sure the target is unique
diff --git a/doc/rtd/static/css/custom.css b/doc/rtd/static/css/custom.css
new file mode 100644
index 00000000..a6a1f527
--- /dev/null
+++ b/doc/rtd/static/css/custom.css
@@ -0,0 +1,248 @@
+/** Fix the font weight (300 for normal, 400 for slightly bold) **/
+/** Should be 100 for all headers, 400 for normal text  **/
+
+h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
+    font-weight: 200;
+}
+
+.toc-title {
+    font-weight: 400;
+}
+
+div.page, li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
+    font-weight: 300;
+    line-height: 1.5;
+    font-size: var(--font-size--normal);
+}
+
+/** Semantic markup styling **/
+strong.command {
+    font-family: var(--font-stack--monospace);
+    font-size: var(--font-size--medium);
+    background: var(--color-inline-code-background);
+    padding: 0.1em 0.2em;
+}
+
+/** Side bars (side-bar tree = left, toc-tree = right) **/
+div.sidebar-tree {
+    font-weight: 200;
+    line-height: 1.5;
+    font-size: var(--font-size--normal);
+}
+
+div.toc-tree {
+    font-weight: 200;
+    font-size: var(--font-size--medium);
+    line-height: 1.5;
+}
+
+.sidebar-tree .toctree-l1>.reference, .toc-tree li.scroll-current>.reference {
+    font-weight: 400;
+}
+
+/** List styling   **/
+ol, ul {
+    margin-bottom: 1.5rem;
+    margin-left: 1rem;
+    margin-top: 0;
+    padding-left: 1rem;
+}
+
+/** Table styling **/
+
+th.head {
+    text-transform: uppercase;
+    font-size: var(--font-size--small);
+}
+
+table.docutils {
+    border: 0;
+    box-shadow: none;
+    width:100%;
+}
+
+table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
+    border-right: none;
+    border-left: none;
+}
+
+/* center align table cells with ":-:" */
+td.text-center {
+    text-align: center;
+}
+
+/** No rounded corners **/
+
+.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
+    border-radius: 0;
+}
+
+/** code blocks and literals **/
+code.docutils.literal.notranslate, .highlight pre, pre.literal-block {
+    font-size: var(--font-size--medium);
+    border: none;
+}
+
+
+/** Admonition styling **/
+
+.admonition {
+    font-size: var(--font-size--medium);
+    box-shadow: none;
+}
+
+/** Styling for links **/
+/* unvisited link */
+a:link {
+    color: #06c;
+    text-decoration: none;
+}
+
+/* visited link */
+a:visited {
+    color: #7d42b8;
+    text-decoration: none;
+}
+
+/* mouse over link */
+a:hover {
+    text-decoration: underline;
+}
+
+/* selected link */
+a:active {
+    text-decoration: underline;
+}
+
+a.sidebar-brand.centered {
+    text-decoration: none;
+}
+
+/** Color for the "copy link" symbol next to headings **/
+
+a.headerlink {
+    color: var(--color-brand-primary);
+}
+
+/** Line to the left of the current navigation entry **/
+
+.sidebar-tree li.current-page {
+    border-left: 2px solid var(--color-brand-primary);
+}
+
+/** Some tweaks for issue #16 **/
+
+[role="tablist"] {
+    border-bottom: 1px solid var(--color-sidebar-item-background--hover);
+}
+
+.sphinx-tabs-tab[aria-selected="true"] {
+    border: 0;
+    border-bottom: 2px solid var(--color-brand-primary);
+    background-color: var(--color-sidebar-item-background--current);
+    font-weight:300;
+}
+
+.sphinx-tabs-tab{
+    color: var(--color-brand-primary);
+    font-weight:300;
+}
+
+.sphinx-tabs-panel {
+    border: 0;
+    border-bottom: 1px solid var(--color-sidebar-item-background--hover);
+    background: var(--color-background-primary);
+}
+
+button.sphinx-tabs-tab:hover {
+    background-color: var(--color-sidebar-item-background--hover);
+}
+
+/** 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:
+    ```{rst-class} break-col-4 min-width-4-8
+    ```
+**/
+
+table.dec-font-size {
+    font-size: smaller;
+}
+table.break-col-1 td.text-left:first-child {
+    word-break: break-word;
+}
+table.break-col-4 td.text-left:nth-child(4) {
+    word-break: break-word;
+}
+table.min-width-1-15 td.text-left:first-child {
+    min-width: 15em;
+}
+table.min-width-4-8 td.text-left:nth-child(4) {
+    min-width: 8em;
+}
+
+/** Underline for abbreviations **/
+
+abbr[title] {
+    text-decoration: underline solid #cdcdcd;
+}
+
+/** Use the same style for right-details as for left-details **/
+.bottom-of-page .right-details {
+    font-size: var(--font-size--small);
+    display: block;
+}
+
+/** Version switcher */
+button.version_select {
+  color: var(--color-foreground-primary);
+  background-color: var(--color-toc-background);
+  padding: 5px 10px;
+  border: none;
+}
+
+.version_select:hover, .version_select:focus {
+    background-color: var(--color-sidebar-item-background--hover);
+}
+
+.version_dropdown {
+  position: relative;
+  display: inline-block;
+  text-align: right;
+  font-size: var(--sidebar-item-font-size);
+}
+
+.available_versions {
+  display: none;
+  position: absolute;
+  right: 0px;
+  background-color: var(--color-toc-background);
+  box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
+  z-index: 11;
+}
+
+.available_versions a {
+  color: var(--color-foreground-primary);
+  padding: 12px 16px;
+  text-decoration: none;
+  display: block;
+}
+
+.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
+
+.show {display:block;}
+
+/** Fix for nested numbered list - the nested list is lettered **/
+ol.arabic ol.arabic {
+  list-style: lower-alpha;
+}
+
+/** Make expandable sections look like links **/
+details summary {
+    color: var(--color-link);
+}
+
+/** Context links at the bottom of the page **/
+footer, .page-info .context {
+    font-size: var(--font-size--medium);
+}