Switch theme from furo to pydata-sphinx-theme. (#5)

README.md

@@ -9,7 +9,7 @@ Follow the steps below to build and view the site locally.
 ## Requirements
 
 * [Node.js] >= 16 to be able to [view the output](#viewing-the-output)
-* python3
+* python3 >= 3.10
 * python3-venv
 * [Task]
 

docs/_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;
+}

docs/conf.py

@@ -7,6 +7,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "YScope"
+# NOTE: We don't include a period after "Inc" since the theme adds one already.
+project_copyright = "2023-2024 YScope Inc"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -16,20 +18,49 @@
     "sphinx_design"
 ]
 
-templates_path = ["_templates"]
-exclude_patterns = []
+# -- MyST extensions -----------------------------------------------------------
+# https://myst-parser.readthedocs.io/en/stable/syntax/optional.html
+myst_enable_extensions = [
+    "colon_fence",
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_favicon = "_static/favicon.ico"
 html_title = "YScope Docs"
-html_show_copyright = False
+html_show_copyright = True
+
 html_static_path = ["_static"]
 
-html_theme = "furo"
+html_theme = "pydata_sphinx_theme"
+
+# -- Theme options ------------------------------------------------------------
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html
+
 html_theme_options = {
-    "source_repository": "https://github.com/y-scope/yscope-docs/",
-    "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,
+}
+
+# -- Theme source buttons ------------------------------------------------------
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html
+
+html_context = {
+    "github_user": "y-scope",
+    "github_repo": "yscope-docs",
+    "github_version": "main",
+    "doc_path": "docs",
 }
+
+# -- 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")

requirements.txt

@@ -1,4 +1,4 @@
-furo==2022.12.7
-myst-parser==1.0.0
-sphinx==5.3.0
-sphinx-design==0.3.0
+myst-parser>=2.0.0
+pydata-sphinx-theme>=0.15.2
+sphinx>=7.2.6
+sphinx-design>=0.5.0