From 350b1400f442288eb2ded2f16bbf392c126f1773 Mon Sep 17 00:00:00 2001 From: Steven Loria Date: Fri, 10 Jan 2025 13:03:00 -0500 Subject: [PATCH] Add copy buttons; use shell-session code-blocks --- CONTRIBUTING.rst | 38 ++++++++++++++++++++----------- README.rst | 4 ++-- docs/{about.rst.inc => about.rst} | 4 ++-- docs/conf.py | 9 ++++++-- docs/examples.rst | 22 +++++++++--------- docs/index.rst | 2 +- docs/install.rst | 6 ++--- pyproject.toml | 5 ++-- 8 files changed, 54 insertions(+), 36 deletions(-) rename docs/{about.rst.inc => about.rst} (96%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7afc874e0..da423bd11 100644 --- 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 `_. -:: +.. 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 `_. 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 `_ directory and send a pull request. +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 `_ directory and send a pull request. .. _Sphinx: https://www.sphinx-doc.org/ diff --git a/README.rst b/README.rst index e9ba6515c..ef4430c97 100644 --- a/README.rst +++ b/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 diff --git a/docs/about.rst.inc b/docs/about.rst similarity index 96% rename from docs/about.rst.inc rename to docs/about.rst index 2ac66719d..4f0eebeba 100644 --- a/docs/about.rst.inc +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 57f0f5a90..3881419f6 100644 --- a/docs/conf.py +++ b/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 = "$ " diff --git a/docs/examples.rst b/docs/examples.rst index d01f5b5a1..d617d9a78 100644 --- a/docs/examples.rst +++ b/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 `_ (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 ` 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/ diff --git a/docs/index.rst b/docs/index.rst index 0da06a6b1..049ccfbf0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ marshmallow: simplified object serialization Release v\ |version|. (:doc:`Changelog `) -.. include:: about.rst.inc +.. include:: about.rst Upgrading from an older version? ================================ diff --git a/docs/install.rst b/docs/install.rst index 97da0eb47..f31b8822c 100644 --- a/docs/install.rst +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 44ba2561c..5aec4b95f 100644 --- a/pyproject.toml +++ b/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"]