Merge pull request #962 from Alexander-N/guide

Update README and remove Getting Started section from user guide

README.md

@@ -23,7 +23,7 @@ If you have never used nightly Rust, the official guide has
 about installing it.
 
 PyPy is also supported (via cpyext) for Python 3.5 only, targeted PyPy version is 7.0.0.
-Please refer to the guide for installation instruction against PyPy.
+Please refer to the [pypy section in the guide](https://pyo3.rs/master/pypy.html).
 
 You can either write a native Python module in Rust, or use Python from a Rust binary.
 
@@ -60,13 +60,13 @@ features = ["extension-module"]
 use pyo3::prelude::*;
 use pyo3::wrap_pyfunction;
 
+/// Formats the sum of two numbers as string.
 #[pyfunction]
-/// Formats the sum of two numbers as string
 fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
     Ok((a + b).to_string())
 }
 
-/// This module is a python module implemented in Rust.
+/// A Python module implemented in Rust.
 #[pymodule]
 fn string_sum(py: Python, m: &PyModule) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(sum_as_string))?;
@@ -85,13 +85,14 @@ rustflags = [
 ]
 ```
 
-For developing, you can copy and rename the shared library from the target folder: On MacOS, rename `libstring_sum.dylib` to `string_sum.so`, on Windows `libstring_sum.dll` to `string_sum.pyd` and on Linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the same folder and you'll be able to `import string_sum`.
+While developing, you can symlink (or copy) and rename the shared library from the target folder: On MacOS, rename `libstring_sum.dylib` to `string_sum.so`, on Windows `libstring_sum.dll` to `string_sum.pyd`, and on Linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the same folder and you'll be able to `import string_sum`.
 
-To build, test and publish your crate as a Python module, you can use [maturin](https://github.com/PyO3/maturin) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](examples/word-count), while maturin should work on your crate without any configuration.
+To build, test and publish your crate as a Python module, you can use [maturin](https://github.com/PyO3/maturin) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](https://github.com/PyO3/pyo3/tree/master/examples/word-count), while maturin should work on your crate without any configuration.
 
 ## Using Python from Rust
 
-Add `pyo3` to your `Cargo.toml` like this:
+If you want your Rust application to create a Python interpreter internally and
+use it to run Python code, add `pyo3` to your `Cargo.toml` like this:
 
 ```toml
 [dependencies]
@@ -108,8 +109,8 @@ fn main() -> Result<(), ()> {
     let gil = Python::acquire_gil();
     let py = gil.python();
     main_(py).map_err(|e| {
-        // We can't display python error type via ::std::fmt::Display,
-        // so print error here manually.
+        // We can't display Python exceptions via std::fmt::Display,
+        // so print the error here manually.
         e.print_and_set_sys_last_vars(py);
     })
 }

guide/src/SUMMARY.md

@@ -1,6 +1,5 @@
 # Summary
 
-- [Getting Started](get_started.md)
 - [Python Modules](module.md)
 - [Python Functions](function.md)
 - [Python Classes](class.md)

guide/src/module.md

@@ -1,6 +1,6 @@
 # Python Modules
 
-As shown in the Getting Started chapter, you can create a module as follows:
+You can create a module as follows:
 
 ```rust
 use pyo3::prelude::*;
@@ -34,7 +34,7 @@ fn sum_as_string(a: i64, b: i64) -> String {
 
 The `#[pymodule]` procedural macro attribute takes care of exporting the initialization function of your module to Python. It can take as an argument the name of your module, which must be the name of the `.so` or `.pyd` file; the default is the Rust function's name.
 
-To import the module, either copy the shared library as described in [Get Started](./get_started.md) or use a tool, e.g. `maturin develop` with [maturin](https://github.com/PyO3/maturin) or `python setup.py develop` with [setuptools-rust](https://github.com/PyO3/setuptools-rust).
+To import the module, either copy the shared library as described in [the README](https://github.com/PyO3/pyo3) or use a tool, e.g. `maturin develop` with [maturin](https://github.com/PyO3/maturin) or `python setup.py develop` with [setuptools-rust](https://github.com/PyO3/setuptools-rust).
 
 ## Documentation
 

src/lib.rs

@@ -335,7 +335,6 @@ pub mod doc_test {
     doctest!("../guide/src/debugging.md", guide_debugging_md);
     doctest!("../guide/src/exception.md", guide_exception_md);
     doctest!("../guide/src/function.md", guide_function_md);
-    doctest!("../guide/src/get_started.md", guide_get_started_md);
     doctest!("../guide/src/migration.md", guide_migration_md);
     doctest!("../guide/src/module.md", guide_module_md);
     doctest!(