docs: Use Furo Sphinx theme

- Switch Sphinx theme to https://github.com/pradyunsg/furo
- Apply some custom colors
- Add css styling for audodoc signatures similar to default
  sphinx_rtd_theme
- Remove .. contents:: :local: blocks since this theme has
  a right side local table of contents.
- New pigweed-code-light Pygments theme for use in the
  pw_console and the docs website. Syntax highlighting for
  both matches now.

Change-Id: Iea5daec01d431c0ddffbf11c461493e76dccb710
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/57064
Pigweed-Auto-Submit: Anthony DiGirolamo <tonymd@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Rob Mohr <mohrr@google.com>

7 files changed, 143 insertions, 40 deletions

diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index b2342bfc7..872c5259f 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -177,9 +177,20 @@ pw_doc_gen("docs") {
   output_directory = target_gen_dir
   deps = [
     ":core_docs",
+    ":install_sphinx_themes",
     ":module_docs",
     ":target_docs",
     ":third_party_docs",
     "$dir_pw_env_setup:python.install",
   ]
 }
+
+# Install Pigweed specific sphinx themes.
+pw_python_action("install_sphinx_themes") {
+  module = "pip"
+  args = [
+    "install",
+    "furo",
+  ]
+  stamp = true
+}
diff --git a/docs/_static/css/pigweed.css b/docs/_static/css/pigweed.css
index 030b89a32..8293e881f 100644
--- a/docs/_static/css/pigweed.css
+++ b/docs/_static/css/pigweed.css
@@ -16,39 +16,66 @@
 
 /********** Top left logo & search bar ***********/
 
-/* Hide the version string since we're not yet using it. */
-.wy-side-nav-search div.version {
-  display: none;
-}
-
-/* Hide the little house icon */
-.wy-side-nav-search a.icon.icon-home::before {
-  display: none;
-}
-
 /* Make the "Pigweed" logo text. One day, this will be an image. */
-.wy-side-nav-search a {
+.sidebar-brand {
   font-size: 2em;
   font-family: 'Inconsolata', monospace;
+  font-weight: bold;
   letter-spacing: 0.1em;
   text-transform: uppercase;
 }
+.sidebar-brand-text {
+    font-size: 2.5rem;
+}
+
+/********** General document coloring ***********/
+
+/* Code blocks inside block quotes end up getting italicized. */
+blockquote {
+  font-style: normal;
+}
 
-/* Make the logo background more amaranth-like */
-.wy-side-nav-search {
-  background-color: #e815a5;
+/* Update description list (dl) > description titles (dt) styles for autodoc */
+
+/* Function signatures are gray */
+dl.c>dt, dl.cpp>dt, dl.js>dt, dl.py>dt {
+  border: none;
+  border-left: 3px solid var(--color-api-function-border);
+  background: var(--color-api-function-background);
+  padding-top: 6px;
+  padding-bottom: 6px;
+  padding-left: 0.5em;
+  font-family: var(--font-stack--monospace);
 }
 
-/* The input box has a subtle outline; make it match the background */
-.wy-side-nav-search input[type=text] {
-  border-color: #b529aa;
+/* Adjust indentation for all list types */
+dl.class>dt, dl.enum-class>dt, dl.enum-struct>dt, dl.enum>dt, dl.exception>dt, dl.function>dt, dl.method>dt, dl.type>dt {
+  padding-left: 3em;
+  text-indent: -2.5em;
 }
 
-/********** General document coloring ***********/
+/* Class and describe signatures are blue */
+dl.class>dt, dl.describe>dt {
+  background: var(--color-api-class-background);
+  color: var(--color-api-class-foreground);
+  border: none;
+  border-top: 3px solid var(--color-api-class-border);
+  font-family: var(--font-stack--monospace);
+}
+/* Adjust .. describe:: block padding */
+dl.describe>dt {
+  display: table;
+  padding-top: 6px;
+  padding-bottom: 6px;
+  padding-left: 0.5em;
+  padding-right: 0.5em;
+}
 
-/* Re-color the fixed width text away from the red color to something more
- * gentle, that aligns with the Pigweed colored theme. */
-.rst-content code.literal, .rst-content tt.literal {
-    color: #b756bd;
+/* Diagram backgrounds should always be light */
+div>svg {
+  background: #ffffff;
 }
 
+code.literal {
+  border: 1px solid var(--color-inline-code-border);
+}
diff --git a/docs/conf.py b/docs/conf.py
index 05da9730e..37d547105 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -44,7 +44,8 @@ version = '0.1'
 release = '0.1.0'
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygm = 'sphinx'
+pygments_style = 'pigweed-code-light'
+pygments_dark_style = 'pigweed-code'
 
 extensions = [
     'sphinx.ext.autodoc',  # Automatic documentation for Python code
@@ -73,14 +74,7 @@ m2r_parse_relative_links = True
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
-
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [
-    '_themes',
-]
-
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = 'furo'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -117,6 +111,42 @@ html_css_files = [
     'https://fonts.googleapis.com/css2?family=Inconsolata&display=swap',
 ]
 
+html_theme_options = {
+    'light_css_variables': {
+        # Make the logo text more amaranth-like
+        'color-sidebar-brand-text': '#b529aa',
+        'color-sidebar-search-border': '#b529aa',
+        'color-sidebar-link-text--top-level': '#85004d',
+        'color-sidebar-link-text': '#016074',
+        'color-sidebar-item-background--current': '#f0f0f0',
+        'color-sidebar-item-background--hover': '#ffe2f3',
+        'color-sidebar-item-expander-background--hover': '#ffe2f3',
+        'color-api-function-border': '#cccccc',
+        'color-api-function-background': '#f0f0f0',
+        'color-api-class-background': '#e7f2fa',
+        'color-api-class-foreground': '#2980b9',
+        'color-api-class-border': '#6ab0de',
+        'color-inline-code-background': '#fafafa',
+        'color-inline-code-border': '#cccccc',
+    },
+    'dark_css_variables': {
+        'color-sidebar-brand-text': '#e815a5',
+        'color-sidebar-search-border': '#e815a5',
+        'color-sidebar-link-text--top-level': '#ff79c6',
+        'color-sidebar-link-text': '#8be9fd',
+        'color-sidebar-item-background--current': '#575757',
+        'color-sidebar-item-background--hover': '#4c333f',
+        'color-sidebar-item-expander-background--hover': '#4c333f',
+        'color-api-function-border': '#575757',
+        'color-api-function-background': '#2b2b2b',
+        'color-api-class-background': '#222c35',
+        'color-api-class-foreground': '#87c1e5',
+        'color-api-class-border': '#5288be',
+        'color-inline-code-background': '#2b2b2b',
+        'color-inline-code-border': '#575757',
+    },
+}
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Pigweeddoc'
 
diff --git a/pw_console/py/pw_console/docs/user_guide.rst b/pw_console/py/pw_console/docs/user_guide.rst
index 7bed35118..7f3a299fc 100644
--- a/pw_console/py/pw_console/docs/user_guide.rst
+++ b/pw_console/py/pw_console/docs/user_guide.rst
@@ -10,9 +10,6 @@ User Guide
 The Pigweed Console provides a Python repl (read eval print loop) and log viewer
 in a single-window terminal based interface.
 
-.. contents::
-   :local:
-
 
 Starting the Console
 --------------------
diff --git a/pw_console/py/pw_console/pigweed_code_style.py b/pw_console/py/pw_console/pigweed_code_style.py
index dd115e2a2..361a0ab09 100644
--- a/pw_console/py/pw_console/pigweed_code_style.py
+++ b/pw_console/py/pw_console/pigweed_code_style.py
@@ -14,16 +14,28 @@
 """Brighter PigweedCode pygments style."""
 
 import copy
+import re
+
+from prompt_toolkit.styles.style_transformation import get_opposite_color
+
 from pygments.style import Style  # type: ignore
-from pygments.token import Keyword, Name, Generic  # type: ignore
+from pygments.token import Comment, Keyword, Name, Generic  # type: ignore
 from pygments_style_dracula.dracula import DraculaStyle  # type: ignore
 
 _style_list = copy.copy(DraculaStyle.styles)
 
 # Darker Prompt
 _style_list[Generic.Prompt] = '#bfbfbf'
+# Lighter comments
+_style_list[Comment] = '#778899'
+_style_list[Comment.Hashbang] = '#778899'
+_style_list[Comment.Multiline] = '#778899'
+_style_list[Comment.Preproc] = '#ff79c6'
+_style_list[Comment.Single] = '#778899'
+_style_list[Comment.Special] = '#778899'
 # Lighter output
 _style_list[Generic.Output] = '#f8f8f2'
+_style_list[Generic.Emph] = '#f8f8f2'
 # Remove 'italic' from these
 _style_list[Keyword.Declaration] = '#8be9fd'
 _style_list[Name.Builtin] = '#8be9fd'
@@ -33,10 +45,37 @@ _style_list[Name.Variable.Class] = '#8be9fd'
 _style_list[Name.Variable.Global] = '#8be9fd'
 _style_list[Name.Variable.Instance] = '#8be9fd'
 
+_color_regex = re.compile(r'#(?P<hex>[0-9a-fA-F]{6}) *(?P<rest>.*?)$')
+
+
+def swap_light_dark(color: str) -> str:
+    if not color:
+        return color
+    match = _color_regex.search(color)
+    if not match:
+        return color
+    match_groups = match.groupdict()
+    opposite_color = get_opposite_color(match_groups['hex'])
+    if not opposite_color:
+        return color
+    rest = match_groups.get('rest', '')
+    return '#' + ' '.join([opposite_color, rest])
+
 
 class PigweedCodeStyle(Style):
 
-    background_color = "#2e2e2e"
-    default_style = ""
+    background_color = '#2e2e2e'
+    default_style = ''
 
     styles = _style_list
+
+
+class PigweedCodeLightStyle(Style):
+
+    background_color = '#f8f8f8'
+    default_style = ''
+
+    styles = {
+        key: swap_light_dark(value)
+        for key, value in _style_list.items()
+    }
diff --git a/pw_console/py/setup.py b/pw_console/py/setup.py
index 3b0685269..669192cae 100644
--- a/pw_console/py/setup.py
+++ b/pw_console/py/setup.py
@@ -38,6 +38,8 @@ setuptools.setup(
         'pygments.styles': [
             'pigweed-code = '
             'pw_console.pigweed_code_style:PigweedCodeStyle',
+            'pigweed-code-light = '
+            'pw_console.pigweed_code_style:PigweedCodeLightStyle',
         ],
     },
     install_requires=[
diff --git a/pw_console/testing.rst b/pw_console/testing.rst
index 6b615810e..e4a959b7e 100644
--- a/pw_console/testing.rst
+++ b/pw_console/testing.rst
@@ -8,9 +8,6 @@ completely test in an automated fashion. Unit tests that don't depend on the
 user interface are preferred but not always possible. For those situations
 manual tests should be added here to validate expected behavior.
 
-.. contents::
-  :local:
-
 Run in Test Mode
 ----------------