docs: Switch theme from furo to pydata-sphinx-theme; Remove tippy ext…

…ension. (#49)

docs/README.md

@@ -11,6 +11,7 @@ documentation website for this package:
 * All the [requirements](../README.md#requirements) for building the Python
   package.
 * [Node.js] >= 16 to be able to [view the output](#viewing-the-output)
+* Python 3.10 or later
 
 ## Build Commands
 

docs/conf/conf.py

@@ -2,48 +2,69 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "clp-ffi-py"
+# NOTE: We don't include a period after "Inc" since the theme adds one already.
+copyright = "2023-2024 YScope Inc"
 
 # -- General configuration -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "myst_parser",
     "sphinx_design",
-    "sphinx_tippy",
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
     "sphinx_copybutton",
 ]
 
-templates_path = ["_templates"]
+# -- MyST extensions -----------------------------------------------------------
+# https://myst-parser.readthedocs.io/en/stable/syntax/optional.html
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+# -- Sphinx autodoc options ----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+autoclass_content = "class"
+autodoc_class_signature = "separated"
+autodoc_typehints = "description"
 
 # -- HTML output options -------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_favicon = "https://docs.yscope.com/_static/favicon.ico"
 html_title = "clp-ffi-py"
-html_show_copyright = False
+html_show_copyright = True
+
 html_static_path = ["../src/_static"]
 
-html_theme = "furo"
+html_theme = "pydata_sphinx_theme"
+
+# -- Theme options -------------------------------------------------------------
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html
 
-# -- Furo theme options --------------------------------------------------------
-# https://furo.readthedocs.io/customisation/index.html
 html_theme_options = {
-    "source_repository": "https://github.com/y-scope/clp-ffi-py/",
-    "source_branch": "main",
-    "source_directory": "docs",
+    "footer_start": ["copyright"],
+    "footer_center": [],
+    "footer_end": ["theme-version"],
+    "primary_sidebar_end": [],
+    "secondary_sidebar_items": ["page-toc", "edit-this-page"],
+    "show_prev_next": False,
+    "use_edit_page_button": True,
 }
 
-# -- MyST extensions -----------------------------------------------------------
-# https://myst-parser.readthedocs.io/en/stable/syntax/optional.html
-myst_enable_extensions = [
-    "colon_fence",
-]
+# -- Theme source buttons ------------------------------------------------------
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html
 
-# -- Sphinx autodoc options ----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+html_context = {
+    "github_user": "y-scope",
+    "github_repo": "clp-ffi-py",
+    "github_version": "main",
+    "doc_path": "docs/src",
+}
 
-autoclass_content = "class"
-autodoc_class_signature = "separated"
-autodoc_typehints = "description"
+# -- Theme custom CSS and JS ---------------------------------------------------
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/static_assets.html
+
+def setup(app):
+    app.add_css_file("custom.css")

docs/requirements.txt

@@ -1,6 +1,5 @@
-furo>=2023.8.19
 myst-parser>=2.0.0
-sphinx>=7.1.2
-sphinx-design>=0.5.0
+pydata-sphinx-theme>=0.15.2
+sphinx>=7.2.6
+sphinx_design>=0.5.0
 sphinx-copybutton>=0.5.2
-sphinx_tippy>=0.4.1

docs/src/_static/custom.css

@@ -0,0 +1,21 @@
+html[data-theme="dark"], html[data-theme="light"] {
+    --pst-color-primary: #3399ff;
+    --pst-color-secondary: #9580ff;
+}
+
+a {
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/*
+Remove margin from sidebar-primary-items__end so that we don't have an unnecessary scrollbar. We're
+not using the end items currently.
+*/
+.bd-sidebar-primary .sidebar-primary-items__end {
+    margin-top: 0;
+    margin-bottom: 0;
+}