Add docs

CHANGELOG.md

@@ -9,7 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Added
 
-- New outputs: `steps.supported-pythons-setter.outputs.supported_python_classifiers_json_array` and `steps.supported-pythons-setter.outputs.supported_python_classifiers_json_job_matrix_value`.
+- New outputs: `supported_python_classifiers_json_array` and `supported_python_classifiers_json_job_matrix_value`.
 
   They are extracted from the trove classifiers defined in the package metadata (for example, `Programming Language :: Python :: 3.12`) and allow you to define the Python versions matrix for your CI jobs without duplicating this information.
   [#80](https://github.com/hynek/build-and-inspect-python-package/pull/80)

README.md

@@ -43,6 +43,13 @@ It uploads every commit on `main` to [Test PyPI](https://test.pypi.org/project/s
   This is easily achievable using tools like [*setuptools-scm*](https://setuptools-scm.readthedocs.io/) or [*hatch-vcs*](https://github.com/ofek/hatch-vcs), but beyond the scope of this humble README.
 
 
+### Define Python Version Matrix Based On Package Metadata
+
+*build-and-inspect-python-package* extracts the Python versions your package supports from the trove classifiers in your package’s metadata and offers them as an action output.
+
+That means that you can define your CI matrix based on the Python versions your package supports without duplicating the information between your package configuration and your CI configuration.
+
+
 ### Applications
 
 If you package an **application** as a Python package, this action is useful to double-check you're shipping everything you need, including all templates, translation files, et cetera.
@@ -92,14 +99,24 @@ While *build-and-inspect-python-package* will build a wheel for you by default,
 
 ### Outputs
 
-- `dist`: the location with the built packages.
+- `dist`: The location with the built packages.
 
   See, for example, how [*argon2-cffi-bindings*](https://github.com/hynek/argon2-cffi-bindings/blob/daff9ceb693312ab8257c60db4cd1c13cd866a35/.github/workflows/ci.yml#L83-L97) uses this feature to check the built wheels don't break a package that depends on it.
 
+- `supported_python_classifiers_json_array`: A JSON array of Python versions that are supported by the package as defined by the trove classifiers in the package metadata (for example, `Programming Language :: Python :: 3.12`).
+
+  You can assign this to a matrix strategy key in your CI job (for example, `strategy.matrix.pathon-version`) to test against multiple Python versions without duplicating the information.
+
+  If all this sounds confusing: Check out our [supported Pythons CI workflow] for a realistic example.
+
+- `supported_python_classifiers_json_job_matrix_value`: Same as `supported_python_classifiers_json_array`, but it's a mapping with the JSON array bound to the `python-version` key.
+
+  This is useful if you only want to define a matrix based on Python versions, because then you can just assign this to `strategy.matrix`.
+
 
 ### Artifacts
 
-After a successful run, you'll find multiple artifacts in the run's Summary view:
+After a successful run, you'll find the following artifacts in the run's Summary view:
 
 - **Packages**: The built packages.
   Perfect for [automated PyPI upload workflows][automated]!
@@ -112,6 +129,8 @@ After a successful run, you'll find multiple artifacts in the run's Summary view
 
 [Our CI](.github/workflows/ci.yml) uses all inputs and outputs, if you want to see them in action.
 
+Our [supported Pythons CI workflow] demonstrates how to use `supported_python_classifiers_json_array` to set up a matrix of Python versions for your CI jobs without duplicating the information with your packaging metadata.
+
 
 ## License
 
@@ -120,3 +139,4 @@ The scripts and documentation in this project are released under the [MIT Licens
 [automated]: https://github.com/python-attrs/attrs/blob/main/.github/workflows/pypi-package.yml
 [*cibuildwheel*]: https://cibuildwheel.pypa.io/
 [*setuptools-scm*]: https://setuptools-scm.readthedocs.io/
+[supported Pythons CI workflow]: .github/workflows/ci-supported-pythons.yml