Reactivate doctests for guide

[Alexander-N]

To avoid that the examples in the guide are in a broken state, I'd like to reactivate the tests which were ignored in f9ff7cd. I think assert-rs/docmatic#4 can be mitigated by changing .travis.yml and appveyor.yml so that cargo clean is executed before the tests.

Unfortunately, it seems that extern crate pyo3; has to be added to the examples in order to make the doctests pass (rust-lang/rust#58875). At least we could hide them from the output with #. This would also fix the "Run this code" button in the guide which does not work at the moment.

If this sounds ok I could start working on this.

[konstin]

I'd love to have doctests on CI!

Playing around with rustdoc, I found that rustdoc --edition=2018 --crate-name pyo3 -L dependency=/home/konsti/pyo3/target/debug/deps --extern pyo3=target/debug/deps/libpyo3-38d2343e3d827133.rlib --test README.md works (where 38d2343e3d827133 varies). So I see two options for implementing this: One would be adding extern crate pyo3; everywhere. The other would be making our own version of docmatic that assembles the above command. (docmatic also doesn't do much more than building a cli invocation - it's 54 line of code)

Also note that you don't need to clean everything, just pyo3, pyo3cls and pyo3-derive-backend. Given that it doesn't work without cleaning up beforehand, I think those test should be hidden behind an off-by-default feature that is activated on ci.

[Alexander-N]

At the moment I think the easiest solution is just adding # extern crate pyo3;.

Other possible solutions could be using skeptic in case this gets solved there (WIP in budziq/rust-skeptic#18 (comment)) or using the external doc feature as in https://github.com/abonander/readme-doctest-poc.

[Alexander-N]

I think the situation could be improved by using doc-comment to test the guide. We could remove the workarounds introduced in #387 and hopefully the solution is more robust since the doctests are integrated with cargo. One could simply add something like this to lib.rs:

# test readme
doctest!("../README.md", readme_md);

# test user guide
doctest!("../guide/src/get_started.md", guide_get_started_md);
doctest!("../guide/src/conversions.md", guide_conversions_md);
doctest!("../guide/src/class.md", guide_class_md);
...

What do you think? New or renamed files would have to be manually added. My guess is that this could also be solved with macros somehow.

[konstin]

I like the idea! doc-comment looks really promising.