Merge branch '3.x-line' into dev

marshmallow-code · Jan 11, 2025 · cac2a47 · cac2a47
2 parents 934defa + a21e451
commit cac2a47
Show file tree

Hide file tree

Showing 38 changed files with 403 additions and 407 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -42,7 +42,7 @@ Setting up for local development
 
 1. Fork marshmallow_ on Github.
 
-::
+.. code-block:: shell-session
 
     $ git clone https://github.com/marshmallow-code/marshmallow.git
     $ cd marshmallow
@@ -51,14 +51,14 @@ Setting up for local development
    Use the following command to install an editable version of
    marshmallow along with its development requirements.
 
-::
+.. code-block:: shell-session
 
     # After activating your virtualenv
     $ pip install -e '.[dev]'
 
 3. Install the pre-commit hooks, which will format and lint your git staged files.
 
-::
+.. code-block:: shell-session
 
     # The pre-commit CLI was installed above
     $ pre-commit install --allow-missing-config
@@ -81,17 +81,21 @@ Pull requests
 
 1. Create a new local branch.
 
-::
+For a new feature:
+
+.. code-block:: shell-session
 
-    # For a new feature
     $ git checkout -b name-of-feature dev
 
-    # For a bugfix
-    $ git checkout -b fix-something 2.x-line
+For a bugfix:
+
+.. code-block:: shell-session
+
+    $ git checkout -b fix-something 3.x-line
 
 2. Commit your changes. Write `good commit messages <https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
 
-::
+.. code-block:: shell-session
 
     $ git commit -m "Detailed commit message"
     $ git push origin name-of-feature
@@ -106,15 +110,21 @@ Pull requests
 Running tests
 +++++++++++++
 
-To run all tests: ::
+To run all tests:
+
+.. code-block:: shell-session
 
     $ pytest
 
-To run formatting and syntax checks: ::
+To run formatting and syntax checks:
+
+.. code-block:: shell-session
 
     $ tox -e lint
 
-(Optional) To run tests in all supported Python versions in their own virtual environments (must have each interpreter installed): ::
+(Optional) To run tests in all supported Python versions in their own virtual environments (must have each interpreter installed):
+
+.. code-block:: shell-session
 
     $ tox
 
@@ -125,7 +135,9 @@ Documentation
 
 Contributions to the documentation are welcome. Documentation is written in `reStructuredText`_ (rST). A quick rST reference can be found `here <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_. Builds are powered by Sphinx_.
 
-To build the docs in "watch" mode: ::
+To build the docs in "watch" mode:
+
+.. code-block:: shell-session
 
    $ tox -e watch-docs
 
@@ -137,7 +149,7 @@ Changes in the `docs/` directory will automatically trigger a rebuild.
 Contributing examples
 +++++++++++++++++++++
 
-Have a usage example you'd like to share? A custom `Field` that others might find useful? Feel free to add it to the `examples <https://github.com/marshmallow-code/marshmallow/tree/dev/examples>`_ directory and send a pull request.
+Have a usage example you'd like to share? A custom `Field <marshmallow.fields.Field>` that others might find useful? Feel free to add it to the `examples <https://github.com/marshmallow-code/marshmallow/tree/dev/examples>`_ directory and send a pull request.
 
 
 .. _Sphinx: https://www.sphinx-doc.org/

diff --git a/README.rst b/README.rst
@@ -20,6 +20,8 @@ marshmallow: simplified object serialization
    :target: https://marshmallow.readthedocs.io/
    :alt: Documentation
 
+.. start elevator-pitch
+
 **marshmallow** is an ORM/ODM/framework-agnostic library for converting complex datatypes, such as objects, to and from native Python datatypes.
 
 .. code-block:: python
@@ -50,20 +52,21 @@ marshmallow: simplified object serialization
     #   'release_date': '1971-12-17',
     #   'title': 'Hunky Dory'}
 
-
 In short, marshmallow schemas can be used to:
 
 - **Validate** input data.
 - **Deserialize** input data to app-level objects.
 - **Serialize** app-level objects to primitive Python types. The serialized objects can then be rendered to standard formats such as JSON for use in an HTTP API.
 
-Get It Now
+Get it now
 ==========
 
-::
+.. code-block:: shell-session
 
     $ pip install -U marshmallow
 
+.. end elevator-pitch
+
 Documentation
 =============
 
@@ -110,6 +113,8 @@ Thank you to all our backers! [`Become a backer`_]
 Sponsors
 --------
 
+.. start sponsors
+
 marshmallow is sponsored by `Route4Me <https://route4me.com>`_.
 
 .. image:: https://github.com/user-attachments/assets/018c2e23-032e-4a11-98da-8b6dc25b9054
@@ -121,6 +126,8 @@ Your logo will be displayed here with a link to your website. [`Become a sponsor
 
 .. _`Become a sponsor`: https://opencollective.com/marshmallow#sponsor
 
+.. end sponsors
+
 Professional Support
 ====================
 

diff --git a/docs/_static/apple-touch-icon.png b/docs/_static/apple-touch-icon.png
diff --git a/docs/_static/custom.css b/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;
+}
diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico
diff --git a/docs/_static/marshmallow-logo-200.png b/docs/_static/marshmallow-logo-200.png
diff --git a/docs/_static/marshmallow-logo-with-title-for-dark-theme.png b/docs/_static/marshmallow-logo-with-title-for-dark-theme.png
diff --git a/docs/_static/marshmallow-logo-with-title.png b/docs/_static/marshmallow-logo-with-title.png
diff --git a/docs/_static/marshmallow-logo.png b/docs/_static/marshmallow-logo.png
diff --git a/docs/_templates/donate.html b/docs/_templates/donate.html
diff --git a/docs/_templates/useful-links.html b/docs/_templates/useful-links.html
diff --git a/docs/about.rst.inc b/docs/about.rst.inc
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
@@ -1,17 +1,23 @@
 .. _api:
 
-*************
-API Reference
-*************
-
 .. toctree::
+    :caption: API Reference
+
     top_level
     marshmallow.schema
     marshmallow.fields
     marshmallow.decorators
     marshmallow.validate
     marshmallow.utils
     marshmallow.experimental.context
-    marshmallow.error_store
-    marshmallow.class_registry
     marshmallow.exceptions
+
+Private API
+===========
+
+.. toctree::
+    :caption: Private API
+
+    marshmallow.types
+    marshmallow.class_registry
+    marshmallow.error_store
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,14 +1,14 @@
 import importlib.metadata
 
-import alabaster
-
 extensions = [
+    "autodocsumm",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc.typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
-    "alabaster",
+    "sphinx_copybutton",
     "sphinx_issues",
-    "autodocsumm",
+    "sphinxext.opengraph",
 ]
 
 primary_domain = "py"
@@ -24,53 +24,35 @@
 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"]
+# Ignore WARNING: more than one target found for cross-reference 'Schema': marshmallow.schema.Schema, marshmallow.Schema
+suppress_warnings = ["ref.python"]
 
 # THEME
 
-html_theme_path = [alabaster.get_path()]
-html_theme = "alabaster"
-html_static_path = ["_static"]
-templates_path = ["_templates"]
-html_show_sourcelink = False
-
+html_theme = "furo"
 html_theme_options = {
-    "logo": "marshmallow-logo.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",
+    "light_logo": "marshmallow-logo-with-title.png",
+    "dark_logo": "marshmallow-logo-with-title-for-dark-theme.png",
+    "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_favicon = "_static/favicon.ico"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_show_sourcelink = False
+ogp_image = "_static/marshmallow-logo-200.png"
 
-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",
-    ],
-}
+# 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"
diff --git a/docs/custom_fields.rst b/docs/custom_fields.rst
@@ -197,5 +197,5 @@ Error messages can also be passed to a `Field's` constructor.
 Next steps
 ----------
 
-- Need to add schema-level validation, post-processing, or error handling behavior? See the :doc:`Extending schemas <extending>` page.
-- For example applications using marshmallow, check out the :doc:`Examples <examples>` page.
+- Need to add schema-level validation, post-processing, or error handling behavior? See the :doc:`extending` page.
+- For example applications using marshmallow, check out the :doc:`examples` page.