docs: fix some sections in the migration guide (#5763)

* docs: fix some sections in the migration guide

* fix fmt

Author: davidhewitt

guide/src/migration.md

@@ -7,23 +7,34 @@ For a detailed list of all changes, see the [CHANGELOG](changelog.md).
 
 ### Default to supporting free-threaded Python
 
+<details open>
+<summary><small>Click to expand</small></summary>
+
 When PyO3 0.23 added support for free-threaded Python, this was as an opt-in feature for modules by annotating with `#[pymodule(gil_used = false)]`.
 
 As the support has matured and PyO3's own API has evolved to remove reliance on the GIL, the time is right to switch the default.
 Modules now automatically allow use on free-threaded Python, unless they directly state they require the GIL with `#[pymodule(gil_used = true)]`.
+</details>
 
 ### Deprecation of automatic `FromPyObject` for `#[pyclass]` types which implement `Clone`
 
+<details open>
+<summary><small>Click to expand</small></summary>
+
 `#[pyclass]` types which implement `Clone` used to also implement `FromPyObject` automatically.
 This behaviour is phased out and replaced by an explicit opt-in.
 Affected types will by marked by a deprecation message.
 To migrate use either
 
 - `from_py_object` to keep the automatic derive, or
 - `skip_from_py_object` to accept the new behaviour
+</details>
 
 ### Deprecation of `Py<T>` constructors from raw pointer
 
+<details open>
+<summary><small>Click to expand</small></summary>
+
 The constructors `Py::from_owned_ptr`, `Py::from_owned_ptr_or_opt`, and `Py::from_owned_ptr_or_err` (and similar "borrowed" variants) perform an unchecked cast to the `Py<T>` target type `T`.
 This unchecked cast is a footgun on APIs where the primary concern is about constructing PyO3's safe smart pointer types correctly from the raw pointer value.
 
@@ -59,8 +70,13 @@ let _: Bound<'_, PyNone> = unsafe { Bound::from_owned_ptr(py, raw_ptr).cast_into
 # })
 ```
 
+</details>
+
 ### Removal of `From<Bound<'_, T>` and `From<Py<T>> for PyClassInitializer<T>`
 
+<details open>
+<summary><small>Click to expand</small></summary>
+
 As part of refactoring the initialization code these impls were removed and its functionality was moved into the generated code for `#[new]`.
 As a small side side effect the following pattern will not be accepted anymore:
 
@@ -88,8 +104,13 @@ let obj_2 = existing_bound.clone();
 # })
 ```
 
+</details>
+
 ### Internal change to use multi-phase initialization
 
+<details open>
+<summary><small>Click to expand</small></summary>
+
 [PEP 489](https://peps.python.org/pep-0489/) introduced "multi-phase initialization" for extension modules which provides ways to allocate and clean up per-module state.
 This is a necessary step towards supporting Python "subinterpreters" which run on their own copy of state.
 
@@ -98,12 +119,13 @@ The possibility of creating and consuming per-module state (and supporting subin
 This should not require migration, nor is there expected to be breakage caused by the change.
 
 Nevertheless, this affects the order of initialization so seemed worth noting in this guide.
+</details>
 
 ## from 0.26.* to 0.27
 
 ### `FromPyObject` reworked for flexibility and efficiency
 
-<details open>
+<details>
 <summary><small>Click to expand</small></summary>
 
 With the removal of the `gil-ref` API in PyO3 0.23 it is now possible to fully split the Python lifetime `'py` and the input lifetime `'a`.
@@ -236,7 +258,10 @@ This is very similar to `serde`s [`Deserialize`] and [`DeserializeOwned`] traits
 [`DeserializeOwned`]: https://docs.rs/serde/latest/serde/de/trait.DeserializeOwned.html
 </details>
 
-## `.downcast()` and `DowncastError` replaced with `.cast()` and `CastError`
+### `.downcast()` and `DowncastError` replaced with `.cast()` and `CastError`
+
+<details>
+<summary><small>Click to expand</small></summary>
 
 The `.downcast()` family of functions were only available on `Bound<PyAny>`.
 In corner cases (particularly related to `.downcast_into()`) this would require use of `.as_any().downcast()` or `.into_any().downcast_into()` chains.
@@ -248,18 +273,23 @@ This produces a nicer experience for both PyO3 module authors and consumers.
 To migrate, replace `.downcast()` with `.cast()` and `DowncastError` with `CastError` (and similar with `.downcast_into()` / `DowncastIntoError` etc).
 
 `CastError` requires a Python `type` object (or other "classinfo" object compatible with `isinstance()`) as the second object, so in the rare case where `DowncastError` was manually constructed, small adjustments to code may apply.
+</details>
 
-## `PyTypeCheck` is now an `unsafe trait`
+### `PyTypeCheck` is now an `unsafe trait`
+
+<details>
+<summary><small>Click to expand</small></summary>
 
 Because `PyTypeCheck` is the trait used to guard the `.cast()` functions to treat Python objects as specific concrete types, the trait is `unsafe` to implement.
 
 This should always have been the case, it was an unfortunate omission from its original implementation which is being corrected in this release.
+</details>
 
 ## from 0.25.* to 0.26
 
 ### Rename of `Python::with_gil`, `Python::allow_threads`, and `pyo3::prepare_freethreaded_python`
 
-<details open>
+<details>
 <summary><small>Click to expand</small></summary>
 
 The names for these APIs were created when the global interpreter lock (GIL) was mandatory.
@@ -274,7 +304,7 @@ For this reason, we chose to rename these to more modern terminology introduced
 
 ### Deprecation of `PyObject` type alias
 
-<details open>
+<details>
 <summary><small>Click to expand</small></summary>
 
 The type alias `PyObject` (aka `Py<PyAny>`) is often confused with the identically named FFI definition `pyo3::ffi::PyObject`.
@@ -284,7 +314,7 @@ To migrate simply replace its usage by the target type `Py<PyAny>`.
 
 ### Replacement of `GILOnceCell` with `PyOnceLock`
 
-<details open>
+<details>
 <summary><small>Click to expand</small></summary>
 
 Similar to the above renaming of `Python::with_gil` and related APIs, the `GILOnceCell` type was designed for a Python interpreter which was limited by the GIL.
@@ -327,7 +357,7 @@ DECIMAL_TYPE.import(py, "decimal", "Decimal")?;
 
 ### Deprecation of `GILProtected`
 
-<details open>
+<details>
 <summary><small>Click to expand</small></summary>
 
 As another cleanup related to concurrency primitives designed for a Python constrained by the GIL, the `GILProtected` type is now deprecated.