Minor documentation improvements

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Changelog
 ---------
 
+3.25.1 (unreleased)
+*******************
+
+Documentation:
+
+- Various documentation improvements (:pr:`2746`).
+
 3.25.0 (2025-01-09)
 *******************
 

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/

README.rst

@@ -57,10 +57,10 @@ In short, marshmallow schemas can be used to:
 - **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
 

docs/about.rst.inc → docs/about.rst

@@ -35,10 +35,10 @@ In short, marshmallow schemas can be used to:
 - **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:: bash
+.. code-block:: shell-session
 
     $ pip install -U marshmallow
 

docs/api_reference.rst

@@ -14,3 +14,4 @@ API Reference
     marshmallow.error_store
     marshmallow.class_registry
     marshmallow.exceptions
+    marshmallow.types

docs/conf.py

@@ -3,12 +3,15 @@
 import alabaster
 
 extensions = [
+    "alabaster",
+    "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"
@@ -34,12 +37,14 @@
 
 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_options = {
-    "logo": "marshmallow-logo.png",
+    "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",
@@ -74,3 +79,10 @@
         "relations.html",
     ],
 }
+ogp_image = "_static/marshmallow-logo.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
+copybutton_prompt_text = "$ "
+
+autodoc_typehints = "both"

docs/examples.rst

@@ -40,7 +40,7 @@ Given the following ``package.json`` file...
 
 We can validate it using the above script.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ python examples/package_json_example.py < package.json
     {'description': 'The Pythonic JavaScript toolkit',
@@ -67,7 +67,7 @@ But if we pass an invalid package.json file...
 
 We see the corresponding error messages.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ python examples/package_json_example.py < invalid_package.json
     ERROR: package.json is invalid
@@ -89,14 +89,14 @@ Assume that ``TextBlob`` objects have ``polarity``, ``subjectivity``, ``noun_phr
 
 First, run the app.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ python examples/textblob_example.py
 
 Then send a POST request with some text with `httpie <https://github.com/jkbr/httpie>`_ (a curl-like tool) for testing the APIs.
 
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ pip install httpie
     $ http POST :5000/api/v1/analyze text="Simple is better"
@@ -150,14 +150,14 @@ Below is a full example of a REST API for a quotes app using `Flask <http://flas
 
 Run the app.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ pip install flask flask-sqlalchemy
     $ python examples/flask_example.py
 
 First we'll POST some quotes.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ pip install httpie
     $ http POST :5000/quotes/ author="Tim Peters" content="Beautiful is better than ugly."
@@ -167,7 +167,7 @@ First we'll POST some quotes.
 
 If we provide invalid input data, we get 400 error response. Let's omit "author" from the input data.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ http POST :5000/quotes/ content="I have no author"
     {
@@ -178,7 +178,7 @@ If we provide invalid input data, we get 400 error response. Let's omit "author"
 
 Now we can GET a list of all the quotes.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ http :5000/quotes/
     {
@@ -200,7 +200,7 @@ Now we can GET a list of all the quotes.
 
 We can also GET the quotes for a single author.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ http :5000/authors/1
     {
@@ -236,14 +236,14 @@ Here, we use `Schema.load <marshmallow.Schema.load>` to validate and deserialize
 
 Run the app.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ pip install flask peewee
     $ python examples/peewee_example.py
 
 After registering a user and creating some todo items in the database, here is an example response.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ pip install httpie
     $ http GET :5000/todos/

docs/extending.rst

@@ -182,7 +182,7 @@ The pipeline for serialization is similar, except that the ``pass_many=True`` pr
 
         # YES
         class MySchema(Schema):
-            field_a = fields.Field()
+            field_a = fields.Raw()
 
             @pre_load
             def preprocess(self, data, **kwargs):
@@ -200,7 +200,7 @@ The pipeline for serialization is similar, except that the ``pass_many=True`` pr
 
         # NO
         class MySchema(Schema):
-            field_a = fields.Field()
+            field_a = fields.Raw()
 
             @pre_load
             def step1(self, data, **kwargs):
@@ -457,6 +457,13 @@ Our application schemas can now inherit from our custom schema class.
 Using context
 -------------
 
+.. warning::
+
+    The ``context`` attribute is deprecated and will be removed in marshmallow 4.
+    Use `contextvars.ContextVar` for passing context to fields, pre-/post-processing methods, and validators instead.
+    marshmallow 4 will also provide an `experimental helper API <https://marshmallow.readthedocs.io/en/latest/marshmallow.experimental.context.html>`_
+    for using context.
+
 The ``context`` attribute of a `Schema <marshmallow.Schema>` is a general-purpose store for extra information that may be needed for (de)serialization. It may be used in both ``Schema`` and ``Field`` methods.
 
 .. code-block:: python

docs/index.rst

@@ -6,7 +6,7 @@ marshmallow: simplified object serialization
 
 Release v\ |version|. (:doc:`Changelog <changelog>`)
 
-.. include:: about.rst.inc
+.. include:: about.rst
 
 Upgrading from an older version?
 ================================

docs/install.rst

@@ -10,13 +10,13 @@ Installing/upgrading from the PyPI
 
 To install the latest stable version from the PyPI:
 
-::
+.. code-block:: shell-session
 
     $ pip install -U marshmallow
 
 To install the latest pre-release version from the PyPI:
 
-::
+.. code-block:: shell-session
 
     $ pip install -U marshmallow --pre
 
@@ -25,7 +25,7 @@ Get the bleeding edge version
 
 To get the latest development version of marshmallow, run
 
-::
+.. code-block:: shell-session
 
     $ pip install -U git+https://github.com/marshmallow-code/marshmallow.git@dev
 

docs/marshmallow.types.rst

@@ -0,0 +1,5 @@
+Types
+=====
+
+.. automodule:: marshmallow.types
+    :members:

docs/quickstart.rst

@@ -491,6 +491,24 @@ If you are consuming and producing data that does not match your schema, you can
 Implicit field creation
 -----------------------
 
+.. warning::
+
+    Implicit field creation is deprecated and is removed in marshmallow 4.
+    Fields should be declared explicitly.
+
+    .. code-block:: python
+
+        # 3.x
+        class UserSchema(Schema):
+            class Meta:
+                fields = ("name", "birthdate")
+
+
+        # 4.x
+        class UserSchema(Schema):
+            name = fields.String()
+            email = fields.Date()
+
 When your model has many attributes, specifying the field type for every attribute can get repetitive, especially when many of the attributes are already native Python datatypes.
 
 The ``fields`` option allows you to specify implicitly-created fields. marshmallow will choose an appropriate field type based on the attribute's type.

pyproject.toml

@@ -33,10 +33,12 @@ Tidelift = "https://tidelift.com/subscription/pkg/pypi-marshmallow?utm_source=py
 
 [project.optional-dependencies]
 docs = [
-  "sphinx==8.1.3",
-  "sphinx-issues==5.0.0",
   "alabaster==1.0.0",
   "autodocsumm==0.2.14",
+  "sphinx-copybutton==0.5.2",
+  "sphinx-issues==5.0.0",
+  "sphinx==8.1.3",
+  "sphinxext-opengraph==0.9.1",
 ]
 tests = ["pytest", "simplejson"]
 dev = ["marshmallow[tests]", "tox", "pre-commit>=3.5,<5.0"]