Documentation cleanup (#2713)

* Clean up fields documentation

* Clean up API reference TOC

CHANGELOG.rst

@@ -9,6 +9,11 @@ Bug fixes:
 - Typing: Fix typing for `Schema.from_dict <marshmallow.schema.Schema.from_dict>` (:issue:`1653`).
   Thanks :user:`SteadBytes` for reporting.
 
+Support:
+
+- Documentation: clean up `marshmallow.fields` API reference (:issue:`2307`).
+  Thanks :user:`AbdealiLoKo` for reporting.
+
 3.23.2 (2024-12-18)
 *******************
 

docs/api_reference.rst

@@ -13,13 +13,3 @@ API Reference
     marshmallow.error_store
     marshmallow.class_registry
     marshmallow.exceptions
-
-.. automodule:: marshmallow
-   :members:
-   :undoc-members:
-   :autosummary:
-
-.. data:: EXCLUDE
-.. data:: INCLUDE
-.. data:: RAISE
-.. data:: missing

docs/conf.py

@@ -8,7 +8,6 @@
     "sphinx.ext.viewcode",
     "alabaster",
     "sphinx_issues",
-    "versionwarning.extension",
     "autodocsumm",
 ]
 
@@ -36,7 +35,6 @@
 html_theme_path = [alabaster.get_path()]
 html_theme = "alabaster"
 html_static_path = ["_static"]
-html_css_files = ["css/versionwarning.css"]
 templates_path = ["_templates"]
 html_show_sourcelink = False
 
@@ -76,21 +74,3 @@
         "relations.html",
     ],
 }
-
-# sphinx-version-warning config
-versionwarning_messages = {
-    "latest": (
-        "This document is for the development version. "
-        'For the stable version documentation, see <a href="/en/stable/">here</a>.'
-    ),
-    "2.x-line": (
-        "marshmallow 2 is no longer supported as of 2020-08-18. "
-        '<a href="https://marshmallow.readthedocs.io/en/latest/upgrading.html#upgrading-to-3-0">'
-        "Update your code to use marshmallow 3</a>."
-    ),
-}
-# Show warning at top of page
-versionwarning_body_selector = "div.document"
-versionwarning_banner_title = ""
-# For debugging locally
-# versionwarning_project_version = "latest"

docs/marshmallow.fields.rst

@@ -3,7 +3,16 @@
 Fields
 ======
 
+Base Field Class
+----------------
+
+.. autoclass:: marshmallow.fields.Field
+    :private-members:
+
+Field Subclasses
+----------------
+
 .. automodule:: marshmallow.fields
     :members:
-    :private-members:
     :autosummary:
+    :exclude-members: Field, default_error_messages, mapping_type, num_type, DESERIALIZATION_CLASS

docs/marshmallow.schema.rst

@@ -4,5 +4,6 @@ Schema
 .. autoclass:: marshmallow.schema.Schema
     :inherited-members:
     :autosummary:
+    :exclude-members: OPTIONS_CLASS
 
 .. autoclass:: marshmallow.schema.SchemaOpts

pyproject.toml

@@ -36,7 +36,6 @@ docs = [
   "sphinx==8.1.3",
   "sphinx-issues==5.0.0",
   "alabaster==1.0.0",
-  "sphinx-version-warning==1.1.2",
   "autodocsumm==0.2.14",
 ]
 tests = ["pytest", "simplejson"]

src/marshmallow/fields.py

@@ -1,5 +1,3 @@
-"""Field classes for various types of data."""
-
 from __future__ import annotations
 
 import collections
@@ -84,7 +82,6 @@ class Field(FieldABC):
     """Basic field from which other fields should extend. It applies no
     formatting by default, and should only be used in cases where
     data does not need to be formatted before being serialized or deserialized.
-    On error, the name of the field will be returned.
 
     :param dump_default: If set, this value will be used during serialization if the
         input value is missing. If not set, the field will be excluded from the
@@ -140,6 +137,9 @@ class Field(FieldABC):
     .. versionchanged:: 3.0.0b8
         Add ``data_key`` parameter for the specifying the key in the input and
         output data. This parameter replaced both ``load_from`` and ``dump_to``.
+
+    .. versionchanged:: 3.13.0
+        Replace ``missing`` and ``default`` parameters with ``load_default`` and ``dump_default``.
     """
 
     # Some fields, such as Method fields and Function fields, are not expected