Improve docs and Remove all-stable feature

Cargo.toml

@@ -38,8 +38,6 @@ rustversion = "1.0"
 [features]
 default = ["macros"]
 macros = ["ctor", "indoc", "inventory", "paste", "pyo3cls", "unindent"]
-# For CI
-all-stable = ["default", "num-bigint", "num-complex"]
 # Optimizes PyObject to Vec conversion and so on.
 nightly = []
 

Makefile

@@ -16,7 +16,7 @@ fmt:
 
 clippy:
 	@touch src/lib.rs  # Touching file to ensure that cargo clippy will re-check the project
-	cargo clippy --features=all-stable --tests -- \
+	cargo clippy --features="default num-bigint num-complex" --tests -- \
 		$(addprefix -D ,${CLIPPY_LINTS_TO_DENY})
 	for example in examples/*; do (cd $$example/; cargo clippy) || exit 1; done
 

ci/travis/guide.sh

@@ -21,7 +21,7 @@ mdbook build -d ../target/guide guide
 
 # Build the doc
 # This builds the book in target/doc
-cargo doc --features=all-stable --no-deps
+cargo doc --features="default num-bigint num-complex" --no-deps
 echo "<meta http-equiv=refresh content=0;url=pyo3/index.html>" > target/doc/index.html
 
 # Get the lastest tag across all branches

guide/src/advanced.md

@@ -29,8 +29,8 @@ extension-module = ["pyo3/extension-module"]
 default = ["extension-module"]
 ```
 
-## `nightly` flag
+## The `nightly` feature
 
-`pyo3/nightly` feature needs nightly compiler, but enables some optimizations as follows:
-- `FromPyObject` for `Vec` and array is optimized when the object can be `PyBuffer`
-- `ToBorrowedObject`, used by `PyDict::set_item` or so, is optimized when the taken object is a Python native type.
+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/class.md

@@ -893,7 +893,7 @@ To enable this, we use a static registry type provided by [inventory](https://gi
 which allows us to collect `impl`s from arbitrary source code by exploiting some binary trick.
 See [inventory: how it works](https://github.com/dtolnay/inventory#how-it-works) and `pyo3_derive_backend::py_class` for more details.
 Also for `#[pyproto]`, we use a similar, but more task-specific registry and
-initialize it by [ctor](https://github.com/mmastrac/rust-ctor) crate.
+initialize it using the [ctor](https://github.com/mmastrac/rust-ctor) crate.
 
 Specifically, the following implementation is generated:
 

guide/src/rust_cpython.md

@@ -6,7 +6,7 @@ This chapter is based on the discussion in [PyO3/pyo3#55](https://github.com/PyO
 
 ## Macros
 
-While rust-cpython has a macro based dsl for declaring modules and classes, PyO3 uses proc macros. PyO3 also doesn't change your struct and functions so you can still use them as normal Rust functions.
+While rust-cpython has a `macro_rules!` based dsl for declaring modules and classes, PyO3 uses proc macros. PyO3 also doesn't change your struct and functions so you can still use them as normal Rust functions.
 
 **rust-cpython**
 

guide/src/trait_bounds.md

@@ -153,6 +153,7 @@ Now we add the PyO3 annotations to the trait implementation:
 impl Model for UserModel {
   // the previous trait implementation
 }
+```
 
 However, the previous code will not compile. The compilation error is the following one:
 `error: #[pymethods] cannot be used on trait impl blocks`

guide/src/types.md

@@ -46,7 +46,7 @@ references is done at runtime using `PyCell`, a scheme very similar to
 
 ## Object types
 
-### [`PyAny`]
+### [`PyAny`][PyAny]
 
 **Represents:** a Python object of unspecified type, restricted to a GIL
 lifetime.  Currently, `PyAny` can only ever occur as a reference, `&PyAny`.
@@ -95,7 +95,7 @@ These types all implement `Deref<Target = PyAny>`, so they all expose the same
 methods which can be found on `PyAny`.
 
 To see all Python types exposed by `PyO3` you should consult the
-[`pyo3::types`] module.
+[`pyo3::types`][pyo3::types] module.
 
 **Conversions:**