Replace Pallets Flask theme with Furo theme for docs

questionlp · Oct 20, 2024 · daf6675 · daf6675
1 parent 9501cd1
commit daf6675
Show file tree

Hide file tree

Showing 12 changed files with 112 additions and 93 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -21,4 +21,4 @@ github:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -v $(O)
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -1,45 +1,54 @@
-/* @import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600;1,700&display=swap'); */
-@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Serif:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600;1,700&display=swap');
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600;1,700&display=swap');
 @import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600;1,700&display=swap');
-
 @media all {
     body, input, div.sphinxsidebar input {
-        /* font-family: "IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; */
-        font-family: "IBM Plex Serif", Georgia, Cambria, "Times New Roman", serif;
         font-size: 1.05rem;
     }
 
-    h1, h2, h3, h4, h5, h6 {
-        font-family: "IBM Plex Serif", Georgia, Cambria, "Times New Roman", serif;
-    }
-
     code, kbd, pre, textarea {
-        font-family: "IBM Plex Mono", Menlo, Consolas, Monaco, "Liberation Mono", "Lucida Console", monospace;
         font-size: 1rem;
     }
 
-    div.sphinxsidebar {
-        font-size: 1rem;
+    p.caption, .caption-text {
+        font-weight: bold;
     }
 
-    nav#contents {
-        margin-left: 1em;
-        padding-bottom: 1em;
-        padding-left: 1em;
-        width: 90%;
+    span.pre {
+        font-family: var(--font-stack--monospace);
     }
 
-    p.caption, .caption-text {
+    code.literal {
+        font-size: 1rem;
+    }
+
+    .toc-title {
         font-weight: bold;
     }
 
+    .toc-tree code.literal {
+        font-size: 0.9rem;
+    }
+
+    div.highlight {
+        border: 1px solid;
+    }
+
     .bolditalic {
         font-style: italic;
         font-weight: bold;
     }
 
+    ul.simple {
+        margin-bottom: 1rem;
+        margin-top: 0;
+    }
+
+    footer, .page-info .context, .bottom-of-page .left-details, .bottom-of-page .right-details {
+        font-size: unset;
+    }
+
     /* Hide "On GitHub" section from versions menu */
     div.injected > div.rst-versions > div.rst-other-versions > dl:nth-child(4) {
         display: none;
     }
-}
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -4,10 +4,9 @@
 #
 # vim: set noai syntax=python ts=4 sw=4:
 import sys
+from email.mime import base
 from pathlib import Path
 
-from pallets_sphinx_themes import ProjectLink  # type: ignore[report-missing-imports]
-
 current_path = Path.cwd()
 sys.path.insert(0, str(current_path.parent))
 
@@ -16,11 +15,11 @@
 author = "Linh Pham"
 
 extensions = [
-    "pallets_sphinx_themes",
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinxext.opengraph",
 ]
 
 templates_path = [
@@ -35,33 +34,9 @@
     "venv",
 ]
 
-html_theme = "flask"
-
-html_context = {
-    "project_links": [
-        ProjectLink("Source Code", "https://github.com/questionlp/wwdtm"),
-        ProjectLink("PyPI", "https://pypi.org/project/wwdtm/"),
-        ProjectLink("Stats API", "https://api.wwdt.me/"),
-        ProjectLink("Stats Page", "https://stats.wwdt.me/"),
-        ProjectLink("Graphs Site", "https://graphs.wwdt.me/"),
-        ProjectLink("Reports Site", "https://reports.wwdt.me/"),
-    ]
-}
+html_theme = "furo"
 
-html_sidebars = {
-    "index": [
-        "globaltoc.html",
-        "project.html",
-        "searchbox.html",
-    ],
-    "**": [
-        "globaltoc.html",
-        # "localtoc.html",
-        "relations.html",
-        "project.html",
-        "searchbox.html",
-    ],
-}
+html_title = "Wait Wait Stats Library"
 
 html_static_path = [
     "_static",
@@ -72,6 +47,58 @@
 ]
 
 html_show_sourcelink = False
+smartquotes = False
+
+base_fonts = '"IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";'
+monospace_fonts = '"IBM Plex Mono", Menlo, Consolas, Monaco, "Liberation Mono", "Lucida Console", monospace;'
+
+html_theme_options = {
+    "light_css_variables": {
+        "font-stack": base_fonts,
+        "font-stack--monospace": monospace_fonts,
+        "color-foreground-primary": "#000000",
+        "color-foreground-secondary": "#161616",
+        "color-foreground-muted": "#21272a",
+        "color-brand-content": "#0043ce",
+        "color-background-primary": "#ffffff",
+        "color-sidebar-background": "#f2f4f8",
+        "color-sidebar-link-text--top-level": "#0043ce",
+        "color-api-name": "#520408",
+        "color-api-pre-name": "#da1e28",
+        "color-highlight-on-target": "#f2f4f8",
+        "color-sidebar-search-foreground": "#000000",
+        "sidebar-item-font-size": "1rem",
+        "toc-font-size": "0.95rem",
+        "toc-title-font-size": "1rem",
+        "color-toc-item-text": "var(--color-foreground-primary);",
+        "color-toc-title-text": "var(--color-foreground-primary);",
+        "code-font-size": "1rem",
+    },
+    "dark_css_variables": {
+        "font-stack": base_fonts,
+        "font-stack--monospace": monospace_fonts,
+        "color-foreground-primary": "#ffffff",
+        "color-foreground-secondary": "#f4f4f4",
+        "color-foreground-muted": "#dde1e6",
+        "color-brand-content": "#78a9ff",
+        "color-background-primary": "#161616",
+        "color-sidebar-background": "#21272a",
+        "color-sidebar-link-text--top-level": "#78a9ff",
+        "color-api-name": "#fa4d56",
+        "color-api-pre-name": "#ffb3b8",
+        "color-highlight-on-target": "#21272a",
+        "color-sidebar-search-foreground": "#ffffff",
+        "sidebar-item-font-size": "1rem",
+        "toc-font-size": "0.95rem",
+        "toc-title-font-size": "1rem",
+        "color-toc-item-text": "var(--color-foreground-primary);",
+        "color-toc-title-text": "var(--color-foreground-primary);",
+        "code-font-size": "1rem",
+    },
+}
+
+pygments_style = "sas"
+pygments_dark_style = "rrt"
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),

diff --git a/docs/index.rst b/docs/index.rst
@@ -40,11 +40,28 @@ Table of Contents
     migrating/index
     changes/index
 
+
+Project Links
+=============
+
+* `Source Code`_
+* `PyPI`_
+* `Wait Wait Stats API`_
+* `Wait Wait Stats Page`_
+* `Wait Wait Graphs`_
+* `Wait Wait Reports`_
+
+
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+
 
 .. _PyPI: https://pypi.org/project/wwdtm/
+.. _Source Code: https://github.com/questionlp/wwdtm/
+.. _Wait Wait Stats API: https://api.stats.wwdt.me/
+.. _Wait Wait Stats Page: https://stats.wwdt.me/
+.. _Wait Wait Graphs: https://graphs.wwdt.me/
+.. _Wait Wait Reports: https://reports.wwdt.me/
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,14 +1,15 @@
 pytest==8.3.3
-black==24.8.0
+black==24.10.0
 
-mysql-connector-python==8.4.0
-numpy==2.1.0
+mysql-connector-python==9.1.0
+numpy==2.1.2
 python-slugify==8.0.4
 pytz==2024.2
 
-Sphinx==8.0.2
-sphinx-autobuild==2024.9.19
-sphinx-autodoc-typehints==2.4.4
+Sphinx==8.1.3
+sphinx-autobuild==2024.10.3
+sphinx-autodoc-typehints==2.5.0
 sphinx-copybutton==0.5.2
-sphinx-toolbox==3.8.0
-Pallets-Sphinx-Themes==2.1.3
+sphinx-toolbox==3.8.1
+sphinxext-opengraph==0.9.1
+furo==2024.8.6
diff --git a/docs/wwdtm/guest.rst b/docs/wwdtm/guest.rst
@@ -7,11 +7,6 @@ Module: guest
 This module provides objects used to retrieve guests, guest information and
 guest details from a copy of the Wait Wait Don't Tell Me! Stats database.
 
-.. contents:: Contents
-    :depth: 1
-    :local:
-    :backlinks: none
-
 Guest
 =====
 

diff --git a/docs/wwdtm/host.rst b/docs/wwdtm/host.rst
@@ -7,11 +7,6 @@ Module: host
 This module provides objects used to retrieve hosts, host information and host
 details from a copy of the Wait Wait Don't Tell Me! Stats database.
 
-.. contents:: Contents
-    :depth: 1
-    :local:
-    :backlinks: none
-
 Host
 ====
 

diff --git a/docs/wwdtm/location.rst b/docs/wwdtm/location.rst
@@ -8,11 +8,6 @@ This module provides objects that are used to retrieve locations, location
 information and location recordings from a copy of the Wait Wait Don't Tell Me!
 Stats database.
 
-.. contents:: Contents
-    :depth: 1
-    :local:
-    :backlinks: none
-
 Location
 ========
 

diff --git a/docs/wwdtm/panelist.rst b/docs/wwdtm/panelist.rst
@@ -8,11 +8,6 @@ This module provides objects used to retrieve panelists, panelist information
 and panelist details from a copy of the Wait Wait Don't Tell Me! Stats
 database.
 
-.. contents:: Contents
-    :depth: 1
-    :local:
-    :backlinks: none
-
 Panelist
 ========
 

diff --git a/docs/wwdtm/pronoun.rst b/docs/wwdtm/pronoun.rst
@@ -7,11 +7,6 @@ Module: pronoun
 This module provides objects used to retrieve pronouns information from
 a copy of the Wait Wait Don't Tell Me! Stats database.
 
-.. contents:: Contents
-    :depth: 1
-    :local:
-    :backlinks: none
-
 Pronouns
 ========
 

diff --git a/docs/wwdtm/scorekeeper.rst b/docs/wwdtm/scorekeeper.rst
@@ -8,11 +8,6 @@ This module provides objects used to retrieve scorekeepers, scorekeeper
 information and scorekeeper details from a copy of the Wait Wait Don't Tell Me!
 Stats database.
 
-.. contents:: Contents
-    :depth: 1
-    :local:
-    :backlinks: none
-
 Scorekeeper
 ===========
 

diff --git a/docs/wwdtm/show.rst b/docs/wwdtm/show.rst
@@ -8,11 +8,6 @@ This module provides objects used to retrieve shows, show information,
 and show details from a copy of the Wait Wait Don't Tell Me! Stats
 database.
 
-.. contents:: Contents
-    :depth: 1
-    :local:
-    :backlinks: none
-
 Show
 ====