More documentation improvements (#2751)

* Add dark mode logo

* Add view button; don't change color of visited links

* Speed up watch-docs; ignore warning about multiple refs to Schema

* Use serif font for admonitions and copy button

* Fix casing for docs links

* Remove usage of implicit field creation; add warning about context

docs/_static/custom.css

@@ -4,12 +4,18 @@ h2, h3, h4, h5, h6 {
   font-weight: 400;
 }
 
-/* Left and ride sidebars */
-.sidebar-drawer, .toc-drawer {
+/* 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 {

docs/conf.py

@@ -29,23 +29,26 @@
 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 = "furo"
 html_theme_options = {
+    "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
-# 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

docs/custom_fields.rst

@@ -99,6 +99,13 @@ Both :class:`Function <marshmallow.fields.Function>` and :class:`Method <marshma
 Adding context to `Method` and `Function` fields
 ------------------------------------------------
 
+.. 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.
+
 A :class:`Function <marshmallow.fields.Function>` or :class:`Method <marshmallow.fields.Method>` field may need information about its environment to know how to serialize a value.
 
 In these cases, you can set the ``context`` attribute (a dictionary) of a `Schema <marshmallow.Schema>`. :class:`Function <marshmallow.fields.Function>` and :class:`Method <marshmallow.fields.Method>` fields will have access to this dictionary.
@@ -162,5 +169,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.

docs/index.rst

@@ -8,20 +8,20 @@ marshmallow
 
 *Object serialization and deserialization, lightweight and fluffy.*
 
-Release v\ |version|. (:doc:`Changelog <changelog>`)
+Release v\ |version|. (:doc:`changelog`)
 
 ----
 
 .. include:: ../README.rst
     :start-after: .. start elevator-pitch
     :end-before: .. end elevator-pitch
 
-Ready to get started? Go on to the :doc:`Quickstart tutorial <quickstart>` or check out some :doc:`Examples <examples>`.
+Ready to get started? Go on to the :doc:`quickstart` or check out some :doc:`examples <examples>`.
 
 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` page for notes on getting your code up-to-date with the latest version.
 
 Why another library?
 =====================

docs/install.rst

@@ -32,4 +32,4 @@ To get the latest development version of marshmallow, run
 
 .. seealso::
 
-    Need help upgrading to newer releases? See the :doc:`Upgrading to Newer Releases <upgrading>` page.
+    Need help upgrading to newer releases? See the :doc:`upgrading` page.

docs/nesting.rst

@@ -306,6 +306,6 @@ If the object to be marshalled has a relationship to an object of the same type,
 Next steps
 ----------
 
-- Want to create your own field type? See the :doc:`Custom Fields <custom_fields>` page.
-- 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.
+- Want to create your own field type? See the :doc:`custom_fields` 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.

docs/quickstart.rst

@@ -37,7 +37,7 @@ Create a schema by defining a class with variables mapping attribute names to :c
 
 .. seealso::
 
-    For a full reference on the available field classes, see the :ref:`API Docs <api_fields>`.
+    For a full reference on the available field classes, see the :ref:`fields module documentation <api_fields>`.
 
 Creating schemas from dictionaries
 ----------------------------------
@@ -280,7 +280,7 @@ You may also pass a collection (list, tuple, generator) of callables to ``valida
 
     You can register a custom error handler function for a schema by overriding the 
     :func:`handle_error <Schema.handle_error>` method. 
-    See the :doc:`Extending Schemas <extending>` page for more info.
+    See the :doc:`extending` page for more info.
 
 .. seealso::
 
@@ -542,7 +542,7 @@ Note that ``name`` will be automatically formatted as a :class:`String <marshmal
 
 Next steps
 ----------
-- Need to represent relationships between objects? See the :doc:`Nesting Schemas <nesting>` page.
-- Want to create your own field type? See the :doc:`Custom Fields <custom_fields>` page.
-- 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 represent relationships between objects? See the :doc:`nesting` page.
+- Want to create your own field type? See the :doc:`custom_fields` 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.

docs/upgrading.rst

@@ -330,7 +330,7 @@ raised at the end of the process.
 When reporting error messages as `dict`, the keys should refer to subitems
 of the item the message refers to, and the values should be error messages.
 
-See the "Schema-level Validation" section of :doc:`Extending Schemas <extending>`
+See the "Schema-level Validation" section of :doc:`extending`
 page for an example.
 
 Schemas raise ``ValidationError`` when deserializing data with unknown keys
@@ -1284,7 +1284,7 @@ The pre- and post-processing API was significantly improved for better consisten
             data["field_a"] -= 1
             return data
 
-See the :doc:`Extending Schemas <extending>` page for more information on the ``pre_*`` and ``post_*`` decorators.
+See the :doc:`extending` page for more information on the ``pre_*`` and ``post_*`` decorators.
 
 Schema validators
 *****************
@@ -1625,7 +1625,7 @@ The default error messages for many fields and validators have been changed for
 More
 ****
 
-For a full list of changes in 2.0, see the :doc:`Changelog <changelog>`.
+For a full list of changes in 2.0, see the :doc:`changelog <changelog>`.
 
 
 Upgrading to 1.2
@@ -1761,4 +1761,4 @@ Other notable changes:
 
 .. seealso::
 
-    See the :doc:`Changelog <changelog>` for a  more complete listing of added features, bugfixes and breaking changes.
+    See the :doc:`changelog <changelog>` for a more complete listing of added features, bugfixes and breaking changes.

docs/why.rst

@@ -37,9 +37,6 @@ As an example, you might have a JSON endpoint for retrieving all information abo
         players = fields.List(fields.Nested(PlayerSchema))
         last_changed = fields.DateTime(format="rfc")
 
-        class Meta:
-            additional = ("title", "date_created", "type", "is_active")
-
 
     # Serializes full game state
     full_serializer = GameStateSchema()

tox.ini

@@ -23,7 +23,7 @@ commands = sphinx-build --fresh-env docs/ docs/_build {posargs}
 [testenv:watch-docs]
 deps = sphinx-autobuild
 extras = docs
-commands = sphinx-autobuild --fresh-env --open-browser docs/ docs/_build {posargs} --watch src/marshmallow --delay 2
+commands = sphinx-autobuild --open-browser docs/ docs/_build {posargs} --watch src/marshmallow --delay 2
 
 [testenv:watch-readme]
 deps = restview