Test examples in user guide with travis

Also ignore inheritance example in class.md since it does not work
currently, see PyO3#381

Author: Alexander-N

Cargo.toml

@@ -55,6 +55,9 @@ extension-module = []
 # are welcome.
 # abi3 = []
 
+# Use this feature to test the examples in the user guide
+test-doc = []
+
 [workspace]
 members = [
     "pyo3cls",

README.md

@@ -51,6 +51,9 @@ features = ["extension-module"]
 **`src/lib.rs`**
 
 ```rust
+// Not required when using Rust 2018
+extern crate pyo3;
+
 use pyo3::prelude::*;
 use pyo3::wrap_pyfunction;
 
@@ -95,6 +98,9 @@ pyo3 = "0.6.0-alpha.4"
 Example program displaying the value of `sys.version`:
 
 ```rust
+// Not required when using Rust 2018
+extern crate pyo3;
+
 use pyo3::prelude::*;
 use pyo3::types::PyDict;
 

ci/travis/test.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 set -ex
 
-cargo test --features "$FEATURES num-complex"
+cargo clean
+cargo test --features "$FEATURES num-complex test-doc"
 if [ $TRAVIS_JOB_NAME = 'Minimum nightly' ]; then
     cargo fmt --all -- --check
     cargo clippy --features "$FEATURES num-complex"

guide/src/class.md

@@ -5,6 +5,7 @@
 To define python custom class, rust struct needs to be annotated with `#[pyclass]` attribute.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 
 #[pyclass]
@@ -34,6 +35,7 @@ You can get an instance of `PyRef` by `PyRef::new`, which does 3 things:
 
 You can use `PyRef` just like `&T`, because it implements `Deref<Target=T>`.
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # use pyo3::types::PyDict;
 #[pyclass]
@@ -53,6 +55,7 @@ dict.set_item("obj", obj).unwrap();
 ### `PyRefMut`
 `PyRefMut` is a mutable version of `PyRef`.
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 #[pyclass]
 struct MyClass {
@@ -70,6 +73,7 @@ obj.num = 5;
 
 You can use it to avoid lifetime problems.
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 #[pyclass]
 struct MyClass {
@@ -109,6 +113,7 @@ To declare a constructor, you need to define a class method and annotate it with
 attribute. Only the python `__new__` method can be specified, `__init__` is not available.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # use pyo3::PyRawObject;
 #[pyclass]
@@ -149,7 +154,8 @@ By default `PyObject` is used as default base class. To override default base cl
 `new` method accepts `PyRawObject` object. `obj` instance must be initialized
 with value of custom class struct. Subclass must call parent's `new` method.
 
-```rust
+```rust,ignore
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # use pyo3::PyRawObject;
 #[pyclass]
@@ -183,7 +189,7 @@ impl SubClass {
    }
 
    fn method2(&self) -> PyResult<()> {
-       self.get_base().method()
+      self.get_base().method()
    }
 }
 ```
@@ -199,6 +205,7 @@ Descriptor methods can be defined in
 attributes. i.e.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # #[pyclass]
 # struct MyClass {
@@ -223,6 +230,7 @@ Descriptor name becomes function name with prefix removed. This is useful in cas
 rust's special keywords like `type`.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # #[pyclass]
 # struct MyClass {
@@ -251,6 +259,7 @@ Also both `#[getter]` and `#[setter]` attributes accepts one parameter.
 If parameter is specified, it is used and property name. i.e.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # #[pyclass]
 # struct MyClass {
@@ -278,6 +287,7 @@ In this case property `number` is defined. And it is available from python code
 For simple cases you can also define getters and setters in your Rust struct field definition, for example:
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 #[pyclass]
 struct MyClass {
@@ -296,6 +306,7 @@ wrappers for all functions in this block with some variations, like descriptors,
 class method static methods, etc.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # #[pyclass]
 # struct MyClass {
@@ -323,6 +334,7 @@ The return type must be `PyResult<T>` for some `T` that implements `IntoPyObject
 get injected by method wrapper. i.e
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # #[pyclass]
 # struct MyClass {
@@ -346,6 +358,7 @@ To specify class method for custom class, method needs to be annotated
 with`#[classmethod]` attribute.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # use pyo3::types::PyType;
 # #[pyclass]
@@ -378,6 +391,7 @@ with `#[staticmethod]` attribute. The return type must be `PyResult<T>`
 for some `T` that implements `IntoPyObject`.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 # #[pyclass]
 # struct MyClass {
@@ -400,6 +414,7 @@ To specify custom `__call__` method for custom class, call method needs to be an
 with `#[call]` attribute. Arguments of the method are specified same as for instance method.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 use pyo3::types::PyTuple;
 # #[pyclass]
@@ -443,6 +458,7 @@ Each parameter could one of following type:
 
 Example:
 ```rust
+# extern crate pyo3;
 # use pyo3::prelude::*;
 use pyo3::types::{PyDict, PyTuple};
 #
@@ -545,6 +561,8 @@ These correspond to the slots `tp_traverse` and `tp_clear` in the Python C API.
 as every cycle must contain at least one mutable reference.
 Example:
 ```rust
+extern crate pyo3;
+
 use pyo3::prelude::*;
 use pyo3::PyTraverseError;
 use pyo3::gc::{PyGCProtocol, PyVisit};
@@ -585,14 +603,16 @@ collector, and it is possible to track them with `gc` module methods.
 Iterators can be defined using the
 [`PyIterProtocol`](https://docs.rs/pyo3/0.6.0-alpha.4/class/iter/trait.PyIterProtocol.html) trait.
 It includes two methods `__iter__` and `__next__`:
-  * `fn __iter__(&mut self) -> PyResult<impl IntoPyObject>`
-  * `fn __next__(&mut self) -> PyResult<Option<impl IntoPyObject>>`
+  * `fn __iter__(slf: PyRefMut<Self>) -> PyResult<impl IntoPyObject>`
+  * `fn __next__(slf: PyRefMut<Self>) -> PyResult<Option<impl IntoPyObject>>`
 
   Returning `Ok(None)` from `__next__` indicates that that there are no further items.
 
 Example:
 
 ```rust
+extern crate pyo3;
+
 use pyo3::prelude::*;
 use pyo3::PyIterProtocol;
 

guide/src/conversions.md

@@ -24,6 +24,7 @@ provides two methods:
 Both methods accept `args` and `kwargs` arguments.
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::types::{PyDict, PyTuple};
 
@@ -61,6 +62,7 @@ fn main() {
 [`IntoPyDict`][IntoPyDict] trait to convert other dict-like containers, e.g. `HashMap`, `BTreeMap` as well as tuples with up to 10 elements and `Vec`s where each element is a two element tuple.
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::types::{IntoPyDict, PyDict};
 use std::collections::HashMap;

guide/src/exception.md

@@ -5,6 +5,7 @@
 You can use the `create_exception!` macro to define a new exception type:
 
 ```rust
+# extern crate pyo3;
 use pyo3::create_exception;
 
 create_exception!(module, MyError, pyo3::exceptions::Exception);
@@ -16,6 +17,7 @@ create_exception!(module, MyError, pyo3::exceptions::Exception);
 For example:
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::create_exception;
 use pyo3::types::PyDict;
@@ -40,6 +42,7 @@ fn main() {
 To raise an exception, first you need to obtain an exception type and construct a new [`PyErr`](https://docs.rs/pyo3/0.2.7/struct.PyErr.html), then call [`PyErr::restore()`](https://docs.rs/pyo3/0.2.7/struct.PyErr.html#method.restore) method to write the exception back to the Python interpreter's global state.
 
 ```rust
+# extern crate pyo3;
 use pyo3::{Python, PyErr};
 use pyo3::exceptions;
 
@@ -64,6 +67,7 @@ has corresponding rust type, exceptions defined by `create_exception!` and `impo
 have rust type as well.
 
 ```rust
+# extern crate pyo3;
 # use pyo3::exceptions;
 # use pyo3::prelude::*;
 # fn check_for_error() -> bool {false}
@@ -82,6 +86,7 @@ Python has an [`isinstance`](https://docs.python.org/3/library/functions.html#is
 in `PyO3` there is a [`Python::is_instance()`](https://docs.rs/pyo3/0.2.7/struct.Python.html#method.is_instance) method which does the same thing.
 
 ```rust
+# extern crate pyo3;
 use pyo3::Python;
 use pyo3::types::{PyBool, PyList};
 
@@ -100,6 +105,7 @@ fn main() {
 To check the type of an exception, you can simply do:
 
 ```rust
+# extern crate pyo3;
 # use pyo3::exceptions;
 # use pyo3::prelude::*;
 # fn main() {
@@ -151,6 +157,7 @@ The code snippet above will raise `OSError` in Python if `TcpListener::bind()` r
 types so `try!` macro or `?` operator can be used.
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 
 fn parse_int(s: String) -> PyResult<usize> {
@@ -168,6 +175,7 @@ It is possible to use exception defined in python code as native rust types.
 for that exception.
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::import_exception;
 

guide/src/function.md

@@ -6,6 +6,7 @@ the function to a [module](./module.md)
 One way is defining the function in the module definition.
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 
 #[pymodule]
@@ -30,6 +31,7 @@ as first parameter, the function name as second and an instance of `Python`
 as third.
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::wrap_pyfunction;
 
@@ -60,6 +62,7 @@ built-ins are new in Python 3 — in Python 2, it is simply considered to be par
 of the doc-string.
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 
 /// add(a, b, /)
@@ -73,7 +76,7 @@ fn add(a: u64, b: u64) -> u64 {
 ```
 
 When annotated like this, signatures are also correctly displayed in IPython.
-```
+```ignore
 >>> pyo3_test.add?
 Signature: pyo3_test.add(a, b, /)
 Docstring: This function adds two unsigned 64-bit integers.

guide/src/get_started.md

@@ -45,6 +45,7 @@ features = ["extension-module"]
 **`src/lib.rs`**
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::wrap_pyfunction;
 
@@ -89,6 +90,7 @@ pyo3 = "0.5"
 Example program displaying the value of `sys.version`:
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::types::PyDict;
 

guide/src/module.md

@@ -3,6 +3,7 @@
 As shown in the Getting Started chapter, you can create a module as follows:
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 
 // add bindings to the generated python module
@@ -52,6 +53,7 @@ Which means that the above Python code will print `This module is implemented in
 In python, modules are first class objects. This means can store them as values or add them to dicts or other modules:
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::{wrap_pyfunction, wrap_pymodule};
 use pyo3::types::PyDict;

guide/src/rust-cpython.md

@@ -25,6 +25,7 @@ py_class!(class MyClass |py| {
 **pyo3**
 
 ```rust
+# extern crate pyo3;
 use pyo3::prelude::*;
 use pyo3::PyRawObject;
 

pyo3-derive-backend/src/pymethod.rs

@@ -182,7 +182,7 @@ fn impl_wrap_init(cls: &syn::Type, name: &syn::Ident, spec: &FnSpec<'_>) -> Toke
         unsafe extern "C" fn __wrap(
             _slf: *mut ::pyo3::ffi::PyObject,
             _args: *mut ::pyo3::ffi::PyObject,
-            _kwargs: *mut ::pyo3::ffi::PyObject) -> libc::c_int
+            _kwargs: *mut ::pyo3::ffi::PyObject) -> ::std::os::raw::c_int
         {
             const _LOCATION: &'static str = concat!(stringify!(#cls),".",stringify!(#name),"()");
             let _pool = ::pyo3::GILPool::new();
@@ -305,7 +305,7 @@ pub(crate) fn impl_wrap_setter(
         #[allow(unused_mut)]
         unsafe extern "C" fn __wrap(
             _slf: *mut ::pyo3::ffi::PyObject,
-            _value: *mut ::pyo3::ffi::PyObject, _: *mut ::std::os::raw::c_void) -> libc::c_int
+            _value: *mut ::pyo3::ffi::PyObject, _: *mut ::std::os::raw::c_void) -> ::std::os::raw::c_int
         {
             const _LOCATION: &'static str = concat!(stringify!(#cls),".",stringify!(#name),"()");
             let _pool = ::pyo3::GILPool::new();

tests/test_doc.rs

@@ -14,17 +14,17 @@ fn assert_file<P: AsRef<Path>>(path: P) {
     doc.test_file(path.as_ref())
 }
 
-#[ignore]
 #[test]
+#[cfg(feature = "test-doc")]
 fn test_guide() {
     let guide_path = PathBuf::from("guide").join("src");
     for entry in guide_path.read_dir().unwrap() {
         assert_file(entry.unwrap().path())
     }
 }
 
-#[ignore]
 #[test]
+#[cfg(feature = "test-doc")]
 fn test_readme() {
     assert_file("README.md")
 }