Migrate docs theme to furo (#2748)

* Initial migration to furo

* Use serif font; add home link

* Clean up logos

docs/_static/custom.css

@@ -0,0 +1,17 @@
+/* Headings */
+
+h2, h3, h4, h5, h6 {
+  font-weight: 400;
+}
+
+/* Left and ride sidebars */
+.sidebar-drawer, .toc-drawer {
+  /* Sans-serif system font stack */
+  font-family: -apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Cantarell, Ubuntu, roboto, noto, arial, sans-serif;
+}
+
+/* Hide ToC caption text within the main body (but leave them in the side-bar). */
+/* https://github.com/hynek/structlog/blob/b488a8bf589a01aabc41e3bf8df81a9848cd426c/docs/_static/custom.css#L17-L20 */
+#furo-main-content span.caption-text {
+  display: none;
+}

docs/api_reference.rst

@@ -1,17 +1,22 @@
 .. _api:
 
-*************
-API Reference
-*************
-
 .. toctree::
+    :caption: API Reference
+
     top_level
     marshmallow.schema
     marshmallow.fields
     marshmallow.decorators
     marshmallow.validate
     marshmallow.utils
-    marshmallow.error_store
-    marshmallow.class_registry
     marshmallow.exceptions
+
+Private API
+===========
+
+.. toctree::
+    :caption: Private API
+
     marshmallow.types
+    marshmallow.class_registry
+    marshmallow.error_store

docs/conf.py

@@ -1,9 +1,6 @@
 import importlib.metadata
 
-import alabaster
-
 extensions = [
-    "alabaster",
     "autodocsumm",
     "sphinx.ext.autodoc",
     "sphinx.ext.autodoc.typehints",
@@ -27,59 +24,29 @@
 master_doc = "index"
 
 project = "marshmallow"
-copyright = '<a href="https://stevenloria.com">Steven Loria</a> and contributors'
+copyright = "Steven Loria and contributors"
 
 version = release = importlib.metadata.version("marshmallow")
 
 exclude_patterns = ["_build"]
 
 # THEME
 
-html_theme_path = [alabaster.get_path()]
-html_theme = "alabaster"
-html_favicon = "_static/favicon.ico"
-html_static_path = ["_static"]
-templates_path = ["_templates"]
-html_show_sourcelink = False
-
+html_theme = "furo"
 html_theme_options = {
-    "logo": "marshmallow-logo-with-title.png",
-    "touch_icon": "apple-touch-icon.png",
-    "description": "Object serialization and deserialization, lightweight and fluffy.",
-    "description_font_style": "italic",
-    "github_user": "marshmallow-code",
-    "github_repo": "marshmallow",
-    "github_banner": True,
-    "github_type": "star",
-    "opencollective": "marshmallow",
-    "tidelift_url": (
-        "https://tidelift.com/subscription/pkg/pypi-marshmallow"
-        "?utm_source=marshmallow&utm_medium=referral&utm_campaign=docs"
-    ),
-    "code_font_size": "0.8em",
-    "warn_bg": "#FFC",
-    "warn_border": "#EEE",
-    # Used to populate the useful-links.html template
-    "extra_nav_links": {
-        "marshmallow @ PyPI": "https://pypi.org/project/marshmallow/",
-        "marshmallow @ GitHub": "https://github.com/marshmallow-code/marshmallow",
-        "Issue Tracker": "https://github.com/marshmallow-code/marshmallow/issues",
-        "Ecosystem": "https://github.com/marshmallow-code/marshmallow/wiki/Ecosystem",
+    "sidebar_hide_name": True,
+    "light_css_variables": {
+        # Serif system font stack: https://systemfontstack.com/
+        "font-stack": "Iowan Old Style, Apple Garamond, Baskerville, Times New Roman, Droid Serif, Times, Source Serif Pro, serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol;",
     },
 }
-
-html_sidebars = {
-    "index": ["about.html", "searchbox.html", "donate.html", "useful-links.html"],
-    "**": [
-        "about.html",
-        "searchbox.html",
-        "donate.html",
-        "useful-links.html",
-        "localtoc.html",
-        "relations.html",
-    ],
-}
-ogp_image = "_static/marshmallow-logo.png"
+html_favicon = "_static/favicon.ico"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_show_sourcelink = False
+# TODO: Dark theme logo
+html_logo = "_static/marshmallow-logo-with-title.png"
+ogp_image = "_static/marshmallow-logo-200.png"
 
 # Strip the dollar prompt when copying code
 # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#strip-and-configure-input-prompts-for-code-cells

docs/donate.rst

@@ -0,0 +1,12 @@
+******
+Donate
+******
+
+If you find marshmallow useful, please consider supporting the team with a donation:
+
+.. image:: https://opencollective.com/marshmallow/donate/[email protected]
+   :target: https://opencollective.com/marshmallow
+   :alt: Donate to our Open Collective
+   :height: 50px
+
+Your donation keeps marshmallow healthy and maintained.

docs/index.rst

@@ -1,11 +1,17 @@
-.. marshmallow documentation master file
+.. meta::
+   :description:
+        marshmallow is an ORM/ODM/framework-agnostic library for converting complex datatypes, such as objects, to and from native Python datatypes.
 
-********************************************
-marshmallow: simplified object serialization
-********************************************
+***********
+marshmallow
+***********
+
+*Object serialization and deserialization, lightweight and fluffy.*
 
 Release v\ |version|. (:doc:`Changelog <changelog>`)
 
+----
+
 .. include:: ../README.rst
     :start-after: .. start elevator-pitch
     :end-before: .. end elevator-pitch
@@ -15,7 +21,7 @@ Ready to get started? Go on to the :doc:`Quickstart tutorial <quickstart>` or ch
 Upgrading from an older version?
 ================================
 
-See the :doc:`Upgrading to Newer Releases <upgrading>` page for notes on getting your code up-to-date with the latest version.
+See the :doc:`Upgrading to newer releases <upgrading>` page for notes on getting your code up-to-date with the latest version.
 
 Why another library?
 =====================
@@ -29,10 +35,18 @@ Sponsors
     :start-after: .. start sponsors
     :end-before: .. end sponsors
 
-Guide
-=====
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+    :titlesonly:
+
+    Home <self>
+
+Usage guide
+===========
 
 .. toctree::
+    :caption: Usage guide
     :maxdepth: 2
 
     install
@@ -43,27 +57,38 @@ Guide
     examples
 
 
-API Reference
+API reference
 =============
 
 .. toctree::
-    :maxdepth: 2
+    :caption: API reference
+    :maxdepth: 1
 
     api_reference
 
-Project Info
-============
+Project info
+=============
 
 .. toctree::
+    :caption: Project info
     :maxdepth: 1
 
     why
     changelog
     upgrading
-    ecosystem
     whos_using
     license
     authors
     contributing
     code_of_conduct
     kudos
+    donate
+
+.. toctree::
+    :hidden:
+    :caption: Useful links
+
+    marshmallow @ PyPI <https://pypi.org/project/marshmallow/>
+    marshmallow @ GitHub <https://github.com/marshmallow-code/marshmallow/>
+    Issue Tracker <https://github.com/marshmallow-code/marshmallow/issues>
+    Ecosystem <https://github.com/marshmallow-code/marshmallow/wiki/Ecosystem>

docs/marshmallow.class_registry.rst

@@ -1,4 +1,4 @@
-Class Registry
+Class registry
 ==============
 
 .. automodule:: marshmallow.class_registry

docs/marshmallow.error_store.rst

@@ -1,4 +1,4 @@
-Error Store
+Error store
 ===========
 
 .. automodule:: marshmallow.error_store

docs/marshmallow.utils.rst

@@ -1,4 +1,4 @@
-Utility Functions
+Utility functions
 =================
 
 .. automodule:: marshmallow.utils

pyproject.toml

@@ -33,8 +33,8 @@ Tidelift = "https://tidelift.com/subscription/pkg/pypi-marshmallow?utm_source=py
 
 [project.optional-dependencies]
 docs = [
-  "alabaster==1.0.0",
   "autodocsumm==0.2.14",
+  "furo==2024.8.6",
   "sphinx-copybutton==0.5.2",
   "sphinx-issues==5.0.0",
   "sphinx==8.1.3",