chore: add more to deprecation page

[skip ci]

Signed-off-by: Henry Schreiner <[email protected]>

Author: henryiii

docs/advanced/deprecated.rst

@@ -1,6 +1,63 @@
+.. _deprecated:
+
 Deprecated
 ##########
 
+The following features were deprecated before pybind11 3.0, and may be removed
+in minor releases of pybind11 3.x.
+
+.. list-table:: Deprecated Features
+   :header-rows: 1
+   :widths: 30 15 10
+
+   * - Feature
+     - Deprecated Version
+     - Year
+   * - ``py::metaclass()``
+     - 2.1
+     - 2017
+   * - ``PYBIND11_PLUGIN``
+     - 2.2
+     - 2017
+   * - ``py::set_error()`` replacing ``operator()``
+     - 2.12
+     - 2024
+   * - ``get_type_overload``
+     - 2.6
+     - 2020
+   * - ``call()``
+     - 2.0
+     - 2016
+   * - ``.str()``
+     - ?
+     -
+   * - ``.get_type()``
+     - 2.6
+     -
+   * - ``==`` and ``!=``
+     - 2.2
+     - 2017
+   * - ``.check()``
+     - ?
+     -
+   * - ``object(handle, bool)``
+     - ?
+     -
+   * - ``error_already_set.clear()``
+     - 2.2
+     - 2017
+   * - ``obj.attr(…)`` as ``bool``
+     - ?
+     -
+   * - ``.contains``
+     - ? (maybe 2.4)
+     -
+   * - ``py::capsule`` two-argument with destructor
+     - ?
+     -
+
+
+
 .. _deprecated_enum:
 
 ``py::enum_``

docs/upgrade.rst

@@ -54,6 +54,10 @@ long-standing obstacle when using pybind11-bound functions with Python features
 that rely on pickling, such as multiprocessing and caching tools.
 See #5580 <https://github.com/pybind/pybind11/pull/5580>_ for details.
 
+Anything producing a deprecation warning in the 2.x series may be removed in a
+future minor release of 3.x. Most of these are still present in 3.0 in order to ease
+transition. The new :doc:`deprecated` page details deprecations.
+
 Migration Recommendations
 -------------------------
 

tools/pybind11Config.cmake.in

@@ -68,11 +68,11 @@ maximum version of CMake to 3.27+, then FindPython is the default (since
 FindPythonInterp/FindPythonLibs has been removed via policy `CMP0148`).
 
 Starting in pybind11 3.0, the new mode is the default, but we provide backward
-compatible names (`PYTHON_*` vs. the new `Python_* names). Set the mode
+compatible names (``PYTHON_*`` vs. the new ``Python_*`` names). Set the mode
 explicitly to avoid the compatibility defines. You can specify this mode
-explicitly by setting `PYBIND11_FINDPYTHON` to `COMPAT`, but if you are changing
-your CMakeLists anyway, please just use the `ON` mode. A future release may
-default to `ON`.
+explicitly by setting ``PYBIND11_FINDPYTHON`` to ``COMPAT``, but if you are changing
+your CMakeLists anyway, please just use the ``ON`` mode. A future release may
+default to ``ON``.
 
 New FindPython mode
 ^^^^^^^^^^^^^^^^^^^