Add copy buttons; use shell-session code-blocks

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/conf.py

@@ -3,12 +3,13 @@
 import alabaster
 
 extensions = [
+    "alabaster",
+    "autodocsumm",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
-    "alabaster",
+    "sphinx_copybutton",
     "sphinx_issues",
-    "autodocsumm",
     "sphinxext.opengraph",
 ]
 
@@ -78,3 +79,7 @@
     ],
 }
 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 = "$ "

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/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
 

pyproject.toml

@@ -33,10 +33,11 @@ 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"]