Update README.md with content 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.
 
@@ -61,13 +61,13 @@ use pyo3::prelude::*;
 use pyo3::wrap_pyfunction;
 
 #[pyfunction]
-/// Formats the sum of two numbers as string
+/// 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.
 #[pymodule]
+/// A Python module implemented in Rust.
 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);
     })
 }