docs: prepare for v3.0.0rc1 (#5589)

* Squashed prepv300/manuscript — 30b9c26 — 2025-03-30 14:56:03 -0700 [skip ci]

[Browse prepv300/manuscript tree](https://github.com/rwgk/pybind11/tree/30b9c268aeb98308ea42aaccfd5fe454e173c6fc)

[Browse prepv300/manuscript commits](https://github.com/rwgk/pybind11/commits/30b9c268aeb98308ea42aaccfd5fe454e173c6fc/)

* docs: update changelog

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

* docs: upgrade guide CMake suggestions

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

* Explain type_caster_enum_type_enabled, copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled, move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled in Upgrade guide.

* Add a small section for py::bind_vector, py::bind_map & py::smart_holder

* Fix tiny oversight: Reference back to the current release v2.13 (not v2.12)

* Remove sentence: Using self._pybind11_conduit_v1_() ... should keep extension compatibility.

This isn't true, because we also modernized `PYBIND11_PLATFORM_ABI_ID`
(which I believe was absolutely necessary). I think it'll be too complicated
to explain that here, and there is a mention in the Upgrade guide.

* Changelog: combine #4953 and #5439

* Trivial whitespace/formatting fixes/enhancements.

* chore: add more to deprecation page

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

* docs: update for recent additions

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

* docs: fixes and set rc1 version

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

* fix: support rc versions

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

* Undo erroneous copilot change: We need to use `detail::enable_if_t`, for compatibility with C++11 and C++14.

* Empty lines cleanup.

* Rewording of "CMake support now defaults to ..." paragraph.

* Add missing backticks in upgrade guide.

* Try :ref:deprecated instead of :doc:deprecated

* docs: last bit of polish

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

* Piggy-back trivial whitespace cleanup that was missed in PR #5669

---------

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

Author: rwgk

docs/advanced/classes.rst

@@ -1384,7 +1384,7 @@ You can do that using ``py::custom_type_setup``:
            auto *type = &heap_type->ht_type;
            type->tp_flags |= Py_TPFLAGS_HAVE_GC;
            type->tp_traverse = [](PyObject *self_base, visitproc visit, void *arg) {
-               // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
+   // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
    #if PY_VERSION_HEX >= 0x03090000
                Py_VISIT(Py_TYPE(self_base));
    #endif

docs/advanced/deprecated.rst

@@ -1,6 +1,72 @@
+.. _deprecated:
+
 Deprecated
 ##########
 
+Support for Python 3.8 is deprecated and will be removed in 3.1.
+
+Support for C++11 is deprecated and will be removed in a future version. Please
+use at least C++14.
+
+Support for FindPythonLibs (not available in CMake 3.26+ mode) is deprecated
+and will be removed in a future version. The default mode is also going to
+change to ``"new"`` from ``"compat"`` in the future.
+
+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_``