Migrate to furo for docs

README.rst

@@ -8,6 +8,8 @@ Homepage: https://marshmallow-sqlalchemy.readthedocs.io/
 
 `SQLAlchemy <http://www.sqlalchemy.org/>`_ integration with the  `marshmallow <https://marshmallow.readthedocs.io/en/latest/>`_ (de)serialization library.
 
+.. start elevator-pitch
+
 Declare your models
 ===================
 
@@ -131,6 +133,8 @@ Get it now
 
 Requires Python >= 3.9, marshmallow >= 3.18.0, and SQLAlchemy >= 1.4.40.
 
+.. end elevator-pitch
+
 Documentation
 =============
 

docs/_static/custom.css

@@ -0,0 +1,23 @@
+/* Headings */
+
+h2, h3, h4, h5, h6 {
+  font-weight: 400;
+}
+
+/* UI elements: left and right sidebars, "Back to top" button, admonitions, Copy button */
+.sidebar-drawer, .toc-drawer, .back-to-top, .admonition, .copybtn {
+  /* 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;
+}
+
+/* Links */
+
+a:link, a:visited {
+  color: var(--color-link);
+}
+
+/* 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,26 +1,22 @@
 .. _api:
 
-*************
-API Reference
-*************
-
 Core
 ====
 
 .. automodule:: marshmallow_sqlalchemy
     :members:
 
-    .. autodata:: marshmallow_sqlalchemy.fields_for_model
-        :annotation: =func(...)
+.. autodata:: marshmallow_sqlalchemy.fields_for_model
+    :annotation: =func(...)
 
-    .. autodata:: marshmallow_sqlalchemy.property2field
-        :annotation: =func(...)
+.. autodata:: marshmallow_sqlalchemy.property2field
+    :annotation: =func(...)
 
-    .. autodata:: marshmallow_sqlalchemy.column2field
-        :annotation: =func(...)
+.. autodata:: marshmallow_sqlalchemy.column2field
+    :annotation: =func(...)
 
-    .. autodata:: marshmallow_sqlalchemy.field_for
-        :annotation: =func(...)
+.. autodata:: marshmallow_sqlalchemy.field_for
+    :annotation: =func(...)
 
 Fields
 ======

docs/conf.py

@@ -1,13 +1,13 @@
 import importlib.metadata
-from collections import OrderedDict
-
-import alabaster
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc.typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinx_copybutton",
     "sphinx_issues",
+    "sphinxext.opengraph",
 ]
 
 primary_domain = "py"
@@ -23,56 +23,37 @@
 
 source_suffix = ".rst"
 master_doc = "index"
+
 project = "marshmallow-sqlalchemy"
 copyright = "Steven Loria and contributors"
 
 version = release = importlib.metadata.version("marshmallow-sqlalchemy")
 
 exclude_patterns = ["_build"]
 
-html_theme_path = [alabaster.get_path()]
-html_theme = "alabaster"
-html_static_path = ["_static"]
-templates_path = ["_templates"]
-html_show_sourcelink = False
+# THEME
 
+html_theme = "furo"
+html_logo = "_static/marshmallow-sqlalchemy-logo.png"
 html_theme_options = {
-    "logo": "marshmallow-sqlalchemy-logo.png",
-    "description": "SQLAlchemy integration with the marshmallow (de)serialization library",
-    "description_font_style": "italic",
-    "github_user": "marshmallow-code",
-    "github_repo": "marshmallow-sqlalchemy",
-    "github_banner": True,
-    "github_button": False,
-    "code_font_size": "0.85em",
-    "warn_bg": "#FFC",
-    "warn_border": "#EEE",
-    # Used to populate the useful-links.html template
-    "extra_nav_links": OrderedDict(
-        [
-            (
-                "marshmallow-sqlalchemy @ PyPI",
-                "http://pypi.python.org/pypi/marshmallow-sqlalchemy",
-            ),
-            (
-                "marshmallow-sqlalchemy @ GitHub",
-                "http://github.com/marshmallow-code/marshmallow-sqlalchemy",
-            ),
-            (
-                "Issue Tracker",
-                "http://github.com/marshmallow-code/marshmallow-sqlalchemy/issues",
-            ),
-        ]
-    ),
+    "source_repository": "https://github.com/marshmallow-code/marshmallow-sqlalchemy",
+    "source_branch": "dev",
+    "source_directory": "docs/",
+    "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;",
+    },
+    "top_of_page_buttons": ["view"],
 }
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_show_sourcelink = False
+ogp_image = "_static/marshmallow-sqlalchemy-logo.png"
 
-html_sidebars = {
-    "index": ["about.html", "useful-links.html", "searchbox.html"],
-    "**": [
-        "about.html",
-        "useful-links.html",
-        "localtoc.html",
-        "relations.html",
-        "searchbox.html",
-    ],
-}
+# Strip the dollar prompt when copying code
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html#strip-and-configure-input-prompts-for-code-cells
+copybutton_prompt_text = "$ "
+
+autodoc_typehints = "both"
+autodoc_member_order = "bysource"