docs: replace extension-module feature in docs (#5588)

* replace `extension-module` feature in docs

* fix guide fmt

* fix copy in bullets

* make toml syntax for referring to pyo3 more consistent

* note packaging tools set env var automatically

* fix invalid toml

* Update pyo3-ffi/README.md

Co-authored-by: Icxolu <[email protected]>

* Update guide/src/building-and-distribution.md

Co-authored-by: Matthijs Kok <[email protected]>

* fixup plugin example README

---------

Co-authored-by: Icxolu <[email protected]>
Co-authored-by: Matthijs Kok <[email protected]>

Author: 3 people

Architecture.md

@@ -151,9 +151,8 @@ Some of the functionality of `pyo3-build-config`:
     entirely and only abi3 extensions can be built.
 - Check if we are building a Python extension.
   - If we are building an extension (e.g., Python library installable by `pip`),
-    we don't link `libpython`.
-    Currently we use the `extension-module` feature for this purpose. This may change in the future.
-    See [#1123](https://github.com/PyO3/pyo3/pull/1123).
+    we don't link `libpython` on most platforms (to allow for statically-linked Python interpreters).
+    The `PYO3_BUILD_EXTENSION_MODULE` environment variable suppresses linking.
 - Cross-compiling configuration
   - If `TARGET` architecture and `HOST` architecture differ, we can find cross compile information
     from environment variables (`PYO3_CROSS_LIB_DIR`, `PYO3_CROSS_PYTHON_VERSION` and

Cargo.toml

@@ -101,9 +101,9 @@ macros = ["pyo3-macros"]
 # Enables multiple #[pymethods] per #[pyclass]
 multiple-pymethods = ["inventory", "pyo3-macros/multiple-pymethods"]
 
-# Use this feature when building an extension module.
-# It tells the linker to keep the python symbols unresolved,
-# so that the module can also be used with statically linked python interpreters.
+# Deprecated: use the `PYO3_BUILD_EXTENSION_MODULE` environment variable when
+# building a Python extension module (set automatically by `setuptools-rust` and
+# `maturin`).
 extension-module = ["pyo3-ffi/extension-module"]
 
 # Use the Python limited API. See https://www.python.org/dev/peps/pep-0384/ for more.

README.md

@@ -71,7 +71,7 @@ name = "string_sum"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "0.27.1", features = ["extension-module"] }
+pyo3 = "0.27.1"
 ```
 
 **`src/lib.rs`**
@@ -138,6 +138,7 @@ Start a new project with `cargo new` and add  `pyo3` to the `Cargo.toml` like th
 ```toml
 [dependencies.pyo3]
 version = "0.27.1"
+# Enabling this cargo feature will cause PyO3 to start a Python interpreter on first call to `Python::attach`
 features = ["auto-initialize"]
 ```
 

examples/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2021"
 rust-version = "1.83"
 
 [dev-dependencies]
-pyo3 = { path = "..", features = ["auto-initialize", "extension-module"] }
+pyo3 = { path = "..", features = ["auto-initialize"] }
 
 [[example]]
 name = "decorator"

examples/decorator/.template/Cargo.toml

@@ -9,4 +9,4 @@ name = "decorator"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "{{PYO3_VERSION}}", features = ["extension-module"] }
+pyo3 = "{{PYO3_VERSION}}"

examples/decorator/Cargo.toml

@@ -9,6 +9,6 @@ name = "decorator"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { path = "../../", features = ["extension-module"] }
+pyo3 = { path = "../../" }
 
 [workspace]

examples/getitem/.template/Cargo.toml

@@ -9,4 +9,4 @@ name = "getitem"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "{{PYO3_VERSION}}", features = ["extension-module"] }
+pyo3 = "{{PYO3_VERSION}}"

examples/getitem/Cargo.toml

@@ -9,6 +9,6 @@ name = "getitem"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { path = "../../", features = ["extension-module"] }
+pyo3 = { path = "../../" }
 
 [workspace]

examples/maturin-starter/.template/Cargo.toml

@@ -9,4 +9,4 @@ name = "maturin_starter"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "{{PYO3_VERSION}}", features = ["extension-module"] }
+pyo3 = "{{PYO3_VERSION}}"

examples/maturin-starter/Cargo.toml

@@ -9,7 +9,7 @@ name = "maturin_starter"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { path = "../../", features = ["extension-module"] }
+pyo3 = { path = "../../" }
 
 [features]
 abi3 = ["pyo3/abi3-py37", "generate-import-lib"]