auto-initialize: add CHANGELOG and docs

Author: davidhewitt

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Added
 - Add support for `#[pyclass(dict)]` and `#[pyclass(weakref)]` with the `abi3` feature on Python 3.9 and up. [#1342](https://github.com/PyO3/pyo3/pull/1342)
 - Add FFI definitions `PyOS_BeforeFork`, `PyOS_AfterFork_Parent`, `PyOS_AfterFork_Child` for Python 3.7 and up. [#1348](https://github.com/PyO3/pyo3/pull/1348)
+- Add `auto-initialize` feature to control whether PyO3 should automatically initialize an embedded Python interpreter. For compatibility this feature is enabled by default in PyO3 0.13.1, but is planned to become opt-in from PyO3 0.14.0. [#1347](https://github.com/PyO3/pyo3/pull/1347)
 - Add support for cross-compiling to Windows without needing `PYO3_CROSS_INCLUDE_DIR`. [#1350](https://github.com/PyO3/pyo3/pull/1350)
 
 ### Changed

guide/src/SUMMARY.md

@@ -16,6 +16,7 @@
 - [GIL, mutability and object types](types.md)
 - [Parallelism](parallelism.md)
 - [Debugging](debugging.md)
+- [Features Reference](features.md)
 - [Advanced Topics](advanced.md)
 - [Building and Distribution](building_and_distribution.md)
 - [PyPy support](pypy.md)

guide/src/advanced.md

@@ -15,9 +15,3 @@ The caveat to these "owned references" is that Rust references do not normally c
 For most use cases this behaviour is invisible. Occasionally, however, users may need to clear memory usage sooner than PyO3 usually does. PyO3 exposes this functionality with the  the `GILPool` struct. When a `GILPool` is dropped, ***all*** owned references created after the `GILPool` was created will be cleared.
 
 The unsafe function `Python::new_pool` allows you to create a new `GILPool`. When doing this, you must be very careful to ensure that once the `GILPool` is dropped you do not retain access any owned references created after the `GILPool` was created.
-
-## The `nightly` feature
-
-The `pyo3/nightly` feature needs the nightly Rust compiler. This allows PyO3 to use Rust's unstable specialization feature to apply the following optimizations:
-- `FromPyObject` for `Vec` and `[T;N]` can perform a `memcpy` when the object is a `PyBuffer`
-- `ToBorrowedObject` can skip a reference count increase when the provided object is a Python native type.

guide/src/building_and_distribution.md

@@ -42,7 +42,7 @@ There are two ways to distribute your module as a Python package: The old, [setu
 
 By default, Python extension modules can only be used with the same Python version they were compiled against -- if you build an extension module with Python 3.5, you can't import it using Python 3.8. [PEP 384](https://www.python.org/dev/peps/pep-0384/) introduced the idea of the limited Python API, which would have a stable ABI enabling extension modules built with it to be used against multiple Python versions. This is also known as `abi3`.
 
-Note that [maturin] >= 0.9.0 or [setuptools-rust] >= 0.12.0 is going to support `abi3` wheels.
+Note that [maturin] >= 0.9.0 or [setuptools-rust] >= 0.11.4 support `abi3` wheels.
 See the [corresponding](https://github.com/PyO3/maturin/pull/353) [PRs](https://github.com/PyO3/setuptools-rust/pull/82) for more.
 
 There are three steps involved in making use of `abi3` when building Python packages as wheels:

guide/src/features.md

@@ -0,0 +1,64 @@
+# Features Reference
+
+PyO3 provides a number of Cargo features to customise functionality. This chapter of the guide provides detail on each of them.
+
+By default, the `macros` and `auto-initialize` features are enabled.
+
+## Features for extension module authors
+
+### `extension-module`
+
+This feature is required when building a Python extension module using PyO3.
+
+It tells PyO3's build script to skip linking against `libpython.so` on Unix platforms, where this must not be done.
+
+See the [building and distribution](building_and_distribution.md#linking) section for further detail.
+
+### `abi3`
+
+This feature is used when building Python extension modules to create wheels which are compatible with multiple Python versions.
+
+It restricts PyO3's API to a subset of the full Python API which is guaranteed by [PEP 384](https://www.python.org/dev/peps/pep-0384/) to be forwards-compatible with future Python versions.
+
+See the [building and distribution](building_and_distribution.md#py_limited_apiabi3) section for further detail.
+
+### `abi3-py36` / `abi3-py37` / `abi3-py38` / `abi3-py39`
+
+These features are an extension of the `abi3` feature to specify the exact minimum Python version which the multiple-version-wheel will support.
+
+See the [building and distribution](building_and_distribution.md#minimum-python-version-for-abi3) section for further detail.
+
+## Features for embedding Python in Rust
+
+### `auto-initalize`
+
+This feature changes [`Python::with_gil`](https://docs.rs/pyo3/latest/pyo3/struct.Python.html#method.with_gil) and [`Python::acquire_gil`](https://docs.rs/pyo3/latest/pyo3/struct.Python.html#method.acquire_gil) to automatically initialize a Python interpreter (by calling [`prepare_freethreaded_python`](https://docs.rs/pyo3/latest/pyo3/fn.prepare_freethreaded_python.html)) if needed.
+
+This feature is not needed for extension modules, but for compatibility it is enabled by default until at least the PyO3 0.14 release.
+
+> This feature is enabled by default. To disable it, set `default-features = false` for the `pyo3` entry in your Cargo.toml.
+
+## Advanced Features
+
+### `macros`
+
+This feature enables a dependency on the `pyo3-macros` crate, which provides the procedural macros portion of PyO3's API:
+
+- `#[pymodule]`
+- `#[pyfunction]`
+- `#[pyclass]`
+- `#[pymethods]`
+- `#[pyproto]`
+- `#[derive(FromPyObject)]`
+
+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.
+
+> This feature is enabled by default. To disable it, set `default-features = false` for the `pyo3` entry in your Cargo.toml.
+
+### `nightly`
+
+The `nightly` feature needs the nightly Rust compiler. This allows PyO3 to use Rust's unstable specialization feature to apply the following optimizations:
+- `FromPyObject` for `Vec` and `[T;N]` can perform a `memcpy` when the object supports the Python buffer protocol.
+- `ToBorrowedObject` can skip a reference count increase when the provided object is a Python native type.