guide: rewrite "Building and Distribution" chapter

Author: davidhewitt

README.md

@@ -16,9 +16,9 @@
 
 ## Usage
 
-PyO3 supports Python 3.6 and up. The minimum required Rust version is 1.41.
-
-PyPy is also supported. Some minor features are unavailable on PyPy - please refer to the [pypy section in the guide](https://pyo3.rs/latest/building_and_distribution/pypy.html) for more information.
+PyO3 supports the following software versions:
+  - Python 3.6 and up (CPython and PyPy)
+  - Rust 1.41 and up
 
 You can use PyO3 to write a native Python module in Rust, or to embed Python in a Rust binary. The following sections explain each of these in turn.
 

guide/src/SUMMARY.md

@@ -20,7 +20,6 @@
 - [Advanced Topics](advanced.md)
 - [Building and Distribution](building_and_distribution.md)
   - [Supporting multiple Python versions](building_and_distribution/multiple_python_versions.md)
-  - [PyPy support](building_and_distribution/pypy.md)
 - [Useful Crates](ecosystem.md)
   - [Logging](ecosystem/logging.md)
   - [Async / Await](ecosystem/async-await.md)

guide/src/building_and_distribution.md

@@ -17,7 +17,7 @@ PyO3 provides a struct [`GILOnceCell`] which works equivalently to `OnceCell` bu
 
 ## I can't run `cargo test`: I'm having linker issues like "Symbol not found" or "Undefined reference to _PyExc_SystemError"!
 
-Currently, [#341](https://github.com/PyO3/pyo3/issues/341) causes `cargo test` to fail with linking errors when the `extension-module` feature is activated. For now you can work around this by making the `extension-module` feature optional and running the tests with `cargo test --no-default-features`:
+Currently, [#340](https://github.com/PyO3/pyo3/issues/340) causes `cargo test` to fail with linking errors when the `extension-module` feature is activated. For now you can work around this by making the `extension-module` feature optional and running the tests with `cargo test --no-default-features`:
 
 ```toml
 [dependencies.pyo3]
@@ -138,5 +138,4 @@ print(f"a: {a}\nb: {b}")
 a: <builtins.Inner object at 0x0000020044FCC670>
 b: <builtins.Inner object at 0x0000020044FCC670>
 ```
-The downside to this approach is that any Rust code working on the `Outer` struct now has to acquire the GIL to do anything with its field. 
-
+The downside to this approach is that any Rust code working on the `Outer` struct now has to acquire the GIL to do anything with its field.

guide/src/building_and_distribution/pypy.md

@@ -40,21 +40,22 @@ pub(crate) fn gil_is_acquired() -> bool {
 
 /// Prepares the use of Python in a free-threaded context.
 ///
-/// If the Python interpreter is not already initialized, this function
-/// will initialize it with disabled signal handling
-/// (Python will not raise the `KeyboardInterrupt` exception).
-/// Python signal handling depends on the notion of a 'main thread', which must be
-/// the thread that initializes the Python interpreter.
+/// If the Python interpreter is not already initialized, this function will initialize it with
+/// signal handling disabled (Python will not raise the `KeyboardInterrupt` exception). Python
+/// signal handling depends on the notion of a 'main thread', which must be the thread that
+/// initializes the Python interpreter.
 ///
-/// If both the Python interpreter and Python threading are already initialized,
-/// this function has no effect.
+/// If both the Python interpreter and Python threading are already initialized, this function has
+/// no effect.
+///
+/// This function is unavailable under PyPy because PyPy cannot be embedded in Rust (or any other
+/// software). Support for this is tracked on the
+/// [PyPy issue tracker](https://foss.heptapod.net/pypy/pypy/-/issues/3286).
 ///
 /// # Panics
-/// - If the Python interpreter is initialized but Python threading is not,
-///   a panic occurs.
-///   It is not possible to safely access the Python runtime unless the main
-///   thread (the thread which originally initialized Python) also initializes
-///   threading.
+/// - If the Python interpreter is initialized but Python threading is not, a panic occurs.
+///   It is not possible to safely access the Python runtime unless the main thread (the thread
+///   which originally initialized Python) also initializes threading.
 ///
 /// # Examples
 /// ```rust

guide/src/faq.md

@@ -118,12 +118,9 @@
 //!
 //! # Minimum supported Rust and Python versions
 //!
-//! PyO3 supports Python 3.6+ and Rust 1.41+.
-//!
-//! Building with PyPy is also possible (via cpyext) for Python 3.6,
-//! targeted PyPy version is 7.3+. Please refer to the
-//! [pypy section](https://pyo3.rs/latest/building_and_distribution/pypy.html)
-//! in the guide for more information.
+//! PyO3 supports the following software versions:
+//!   - Python 3.6 and up (CPython and PyPy)
+//!   - Rust 1.41 and up
 //!
 //! # Example: Building a native Python module
 //!
@@ -495,10 +492,6 @@ pub mod doc_test {
         "guide/src/building_and_distribution.md",
         guide_building_and_distribution_md
     );
-    doctest!(
-        "guide/src/building_and_distribution/pypy.md",
-        guide_building_and_distribution_pypy_md
-    );
     doctest!("guide/src/class.md", guide_class_md);
     doctest!("guide/src/class/protocols.md", guide_class_protocols_md);
     doctest!("guide/src/conversions.md", guide_conversions_md);