update README

Author: mckaymatt

README.rst

@@ -1,8 +1,9 @@
-======================
+==================================================
 Cookiecutter PyPackage Rust Cross-Platform Publish
-======================
+==================================================
 
-Cookiecutter_ template for a Python package with a Rust binary module. 
+Cookiecutter_ template for building and releasing Python packages with a Rust binary module. 
+Supports Linux, macOS and Windows.
 
 Rust is a new systems programming language that is comparable in speed with C/C++; 
 but it also has lots of nice modern features like memory safety, a package manager, 
@@ -14,19 +15,30 @@ A very important goal of the project is that it be able to produce a binary
 distribution (Wheel) which will not require the end user to actually compile 
 the Rust code themselves. 
 
-An example output of this cookiecutter can be seen at rust_pypi_example_. 
+A binary wheel is produced for Linux and OSX by TravisCI_. A windows wheel is built 
+for Windows with appveyor_. 
+
+Example Output
+--------------
+
+An exmple project made by this cookiecutter can be seen on github at mckaymatt/rust_pypi_example_. 
 In the example I wrote a cli in Python that interops via CFFI with a Rust binary.
-I used a tool called setuptools-rust which enables setuptools to handle compiling 
+I used a tool called PyO3/setuptools-rust_ which enables setuptools to handle compiling 
 just like it would with C.
 
-A binary wheel is produced for Linux and OSX by TravisCI_. A windows wheel is built 
-for Windows with appveyor_. 
+The binary wheels can be seen on Pypi at pypi.python.org/pypi/rust-pypi-example_. 
+You should be able to install the package on your platform with::
 
+ pip install rust_pypi_example
+ # test if a number is prime
+ rust_pypi_example 13
+ 
+Please create an issue_ if you encounter any problems and include details about your platform.
 
 Supported platforms
------------------------------
+-------------------
 * manylinux_X86_64 and manylinux_i686
-* OSX 
+* macOS/OSX 
 * Windows
 
 Features
@@ -42,7 +54,10 @@ Features
 
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
 .. _appveyor: https://www.appveyor.com/
-.. _rust_pypi_example: https://github.com/mckaymatt/rust_pypi_example
+.. _mckaymatt/rust_pypi_example: https://github.com/mckaymatt/rust_pypi_example
+.. _PyO3/setuptools-rust: https://github.com/PyO3/setuptools-rust
+.. _pypi.python.org/pypi/rust-pypi-example: https://pypi.python.org/pypi/rust-pypi-example
+.. _issue: https://github.com/mckaymatt/cookiecutter-pypackage-rust-cross-platform-publish/issues/new
 
 Quickstart
 ----------
@@ -62,16 +77,36 @@ After you finish answering the promps, the new project will be made.
 
 Local Development Workflow / Hello World
 ----------------------------------------
-This depends on you having ``Make``, ``virtualenv``, and the Rust compiler. Get the Rust compiler from Rustup_
+This depends on you having ``virtualenv``, and the Rust compiler. Get the Rust compiler from Rustup_. Linux/macOS 
+users will also need ``Make``. 
 
-I will also mention that the Makefile workflow doesn't quite work on Windows yet, but it's still pretty easy 
-to get going. You basically make a virtualenv, install the dev dependencies and run ``python setup.py test|install|bdist_wheel|develop`` depending on what you want to do.
+**Linux/macOS**
 
-Still with me? Okay, you are now ready to build your first Rust wheel locally. 
-Go into the directory that Cookiecutter just created and perform your first build locally with:
+The entire local process of building and testing (including 
+creating and activating a virtualenv) is conducted by a single Make command::
 
+ # cd to new project. The default name is rust_pypi_example
+ cd rust_pypi_example
  make local-test
 
+I will note that the virtualenv created by Make seems to have some issues if you try to activate it. 
+If you want to work interactivly you should build your own virtualenv and use that instead. 
+
+**Windows**
+
+The Makefile workflow doesn't quite work on Windows yet, but it's still pretty easy 
+to get going. You basically make a virtualenv, install the dev dependencies and run ``python setup.py test|install|bdist_wheel|develop`` depending on what you want to do.
+
+Go into the directory that Cookiecutter just created (default is rust_pypi_example) and perform your 
+first build locally with::
+
+ # make a virtualenv and activate it
+ pip install -U pip
+ pip install -r requirements_dev.txt
+ python setup.py build_ext # compile ext
+ python setup.py test # test
+ python setup.py bdist_wheel # to make the wheel. Always build_ext first
+
 W00t. You just tested, compiled and packaged you're first Python wheel with a Rust module. 
 
 .. _Rustup: https://www.rustup.rs/
@@ -92,6 +127,22 @@ Set Up Cross-Platform CI, Build and Release
 
 .. _`pip docs for requirements files`: https://pip.pypa.io/en/stable/user_guide/#requirements-files
 
+Known Bugs
+----------
+If you don't run **build_ext** before **bdist_wheel**, the resulting wheel will not have the shared library
+compiled by Cargo. In other words::
+
+ # This alone will make a defective wheel
+ python setup.py bdist_wheel
+
+ # this will work
+ python setup.py build_ext
+ python setup.py bdist_wheel
+ 
+TODOs
+-----
+
+[ ] source distributions.
 
 For more details, see the `cookiecutter-pypackage tutorial`_.