guide: bump to mdbook 0.5 (#5630)

* guide: bump to mdbook 0.5

* bump mdbook pins

* fix mdbook warnings

* use mdbook 0.5 admonitions

* fix `rumdl` issues

* fix heading id

* remove warning div class

Author: davidhewitt

.github/workflows/netlify-build.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Setup mdBook
         uses: taiki-e/install-action@v2
         with:
-          tool: mdbook@0.4, mdbook-tabs@0.2, lychee
+          tool: mdbook@0.5, mdbook-tabs@0.3, lychee
 
       - name: Prepare tag
         id: prepare_tag

guide/book.toml

@@ -1,10 +1,10 @@
 [book]
 title = "PyO3 user guide"
 description = "PyO3 user guide"
-author = "PyO3 Project and Contributors"
+authors = ["PyO3 Project and Contributors"]
 
 [preprocessor.pyo3_version]
-command = "python3 guide/pyo3_version.py"
+command = "python3 pyo3_version.py"
 
 [preprocessor.tabs]
 

guide/pyo3_version.py

@@ -6,7 +6,7 @@
     - {{#PYO3_CRATE_VERSION}} with a relevant toml snippet (e.g. 'version = "0.13.2"')
 
 
-Tested against mdbook 0.4.10.
+Tested against mdbook 0.5.0.
 """
 
 import json
@@ -28,26 +28,26 @@
     PYO3_CRATE_VERSION = f'version = "{version}"'
 
 
-def replace_section_content(section):
-    if not isinstance(section, dict) or "Chapter" not in section:
+def replace_item_content(item):
+    if not isinstance(item, dict) or "Chapter" not in item:
         return
 
     # Replace raw and url-encoded forms
-    section["Chapter"]["content"] = (
-        section["Chapter"]["content"]
+    item["Chapter"]["content"] = (
+        item["Chapter"]["content"]
         .replace("{{#PYO3_VERSION_TAG}}", PYO3_VERSION_TAG)
         .replace("{{#PYO3_DOCS_URL}}", PYO3_DOCS_URL)
         .replace("{{#PYO3_DOCS_VERSION}}", PYO3_DOCS_VERSION)
         .replace("{{#PYO3_CRATE_VERSION}}", PYO3_CRATE_VERSION)
     )
 
-    for sub_item in section["Chapter"]["sub_items"]:
-        replace_section_content(sub_item)
+    for sub_item in item["Chapter"]["sub_items"]:
+        replace_item_content(sub_item)
 
 
 for line in sys.stdin:
     if line:
         [context, book] = json.loads(line)
-        for section in book["sections"]:
-            replace_section_content(section)
+        for item in book["items"]:
+            replace_item_content(item)
         json.dump(book, fp=sys.stdout)

guide/src/building-and-distribution.md

@@ -247,7 +247,8 @@ See [the relevant section of this guide](./building-and-distribution/multiple-py
 PyO3 is only able to link your extension module to abi3 version up to and including your host Python version.
 E.g., if you set `abi3-py38` and try to compile the crate with a host of Python 3.7, the build will fail.
 
-> Note: If you set more that one of these `abi3` version feature flags the lowest version always wins. For example, with both `abi3-py37` and `abi3-py38` set, PyO3 would build a wheel which supports Python 3.7 and up.
+> [!NOTE]
+> If you set more that one of these `abi3` version feature flags the lowest version always wins. For example, with both `abi3-py37` and `abi3-py38` set, PyO3 would build a wheel which supports Python 3.7 and up.
 
 #### Building `abi3` extensions without a Python interpreter
 

guide/src/class.md

@@ -210,7 +210,7 @@ mod my_module {
 }
 ```
 
-## Bound<T> and interior mutability
+## `Bound<T>` and interior mutability { #bound-and-interior-mutability }
 
 It is often useful to turn a `#[pyclass]` type `T` into a Python object and access it from Rust code.
 The [`Py<T>`] and [`Bound<'py, T>`] smart pointers are the ways to represent a Python object in PyO3's API.
@@ -807,10 +807,12 @@ Python::attach(|py| {
 });
 ```
 
-> Note: if the method has a `Result` return type and returns an `Err`, PyO3 will panic during
+> [!NOTE]
+> If the method has a `Result` return type and returns an `Err`, PyO3 will panic during
 class creation.
 
-> Note: `#[classattr]` does not work with [`#[pyo3(warn(...))]`](./function.md#warn) attribute.
+> [!NOTE]
+> `#[classattr]` does not work with [`#[pyo3(warn(...))]`](./function.md#warn) attribute.
 
 If the class attribute is defined with `const` code only, one can also annotate associated constants:
 

guide/src/class/object.md

@@ -181,7 +181,8 @@ This option also requires `eq`: According to the [Python docs](https://docs.pyth
 struct Number(i32);
 ```
 
-> **Note**: When implementing `__hash__` and comparisons, it is important that the following property holds:
+> [!NOTE]
+> When implementing `__hash__` and comparisons, it is important that the following property holds:
 >
 > ```text
 > k1 == k2 -> hash(k1) == hash(k2)

guide/src/class/protocols.md

@@ -84,8 +84,10 @@ The given signatures should be interpreted as follows:
     The implementations of Python's "rich comparison" operators `<`, `<=`, `==`, `!=`, `>` and `>=` respectively.
 
     _Note that implementing any of these methods will cause Python not to generate a default `__hash__` implementation, so consider also implementing `__hash__`._
+
     <details>
     <summary>Return type</summary>
+
     The return type will normally be `bool` or `PyResult<bool>`, however any Python object can be returned.
     </details>
 
@@ -100,6 +102,7 @@ The given signatures should be interpreted as follows:
     _Note that implementing `__richcmp__` will cause Python not to generate a default `__hash__` implementation, so consider implementing `__hash__` when implementing `__richcmp__`._
     <details>
     <summary>Return type</summary>
+
     The return type will normally be `PyResult<bool>`, but any Python object can be returned.
 
     If you want to leave some operations unimplemented, you can return `py.NotImplemented()`
@@ -135,7 +138,8 @@ The given signatures should be interpreted as follows:
 - `__getattribute__(<self>, object) -> object`
 
     <details>
-    <summary>Differences between `__getattr__` and `__getattribute__`</summary>
+    <summary>Differences between <code>__getattr__</code> and <code>__getattribute__</code></summary>
+
     As in Python, `__getattr__` is only called if the attribute is not found
     by normal attribute lookup.  `__getattribute__`, on the other hand, is
     called for *every* attribute access.  If it wants to access existing
@@ -440,7 +444,8 @@ Immutable references do not have to be cleared, as every cycle must contain at l
 - `__traverse__(<self>, pyo3::class::gc::PyVisit<'_>) -> Result<(), pyo3::class::gc::PyTraverseError>`
 - `__clear__(<self>) -> ()`
 
-> Note: `__traverse__` does not work with [`#[pyo3(warn(...))]`](../function.md#warn).
+> [!NOTE]
+> `__traverse__` does not work with [`#[pyo3(warn(...))]`](../function.md#warn).
 
 Example:
 
@@ -471,7 +476,8 @@ impl ClassWithGCSupport {
 Usually, an implementation of `__traverse__` should do nothing but calls to `visit.call`.
 Most importantly, safe access to the interpreter is prohibited inside implementations of `__traverse__`, i.e. `Python::attach` will panic.
 
-> Note: these methods are part of the C API, PyPy does not necessarily honor them. If you are building for PyPy you should measure memory consumption to make sure you do not have runaway memory growth. See [this issue on the PyPy bug tracker](https://github.com/pypy/pypy/issues/3848).
+> [!NOTE]
+> These methods are part of the C API, PyPy does not necessarily honor them. If you are building for PyPy you should measure memory consumption to make sure you do not have runaway memory growth. See [this issue on the PyPy bug tracker](https://github.com/pypy/pypy/issues/3848).
 
 [`PySequence`]: {{#PYO3_DOCS_URL}}/pyo3/types/struct.PySequence.html
 <!-- rumdl-disable-next-line MD053 - false positive -->

guide/src/faq.md

@@ -219,6 +219,7 @@ Some ways to achieve this are:
 If the wrong DLL is linked it is possible that this happened because another program added itself and its own Python DLLs to `PATH`.
 Rearrange your `PATH` variables to give the correct DLL priority.
 
-> **Note**: Changes to `PATH` (or any other environment variable) are not visible to existing shells. Restart it for changes to take effect.
+> [!NOTE]
+> Changes to `PATH` (or any other environment variable) are not visible to existing shells. Restart it for changes to take effect.
 
 For advanced troubleshooting, [Dependency Walker](https://www.dependencywalker.com/) can be used to diagnose linking errors.

guide/src/features.md

@@ -91,6 +91,7 @@ It also provides the `py_run!` macro.
 These macros require a number of dependencies which may not be needed by users who just need PyO3 for Python FFI.
 Disabling this feature enables faster builds for those users, as these dependencies will not be built if this feature is disabled.
 
+> [!NOTE]
 > This feature is enabled by default. To disable it, set `default-features = false` for the `pyo3` entry in your Cargo.toml.
 
 ### `multiple-pymethods`

guide/src/function/signature.md

@@ -114,7 +114,8 @@ num=-1 (was previously=44), py_args=(), name=World, py_kwargs=None
 num=44
 ```
 
-> Note: to use keywords like `struct` as a function argument, use "raw identifier" syntax `r#struct` in both the signature and the function definition:
+> [!NOTE]
+> To use keywords like `struct` as a function argument, use "raw identifier" syntax `r#struct` in both the signature and the function definition:
 >
 > ```rust,no_run
 > # #![allow(dead_code)]