Merge pull request #65 from mwcraig/install-instructions

Add dev install instructions and release instructions

Author: mwcraig

README.md

@@ -40,10 +40,33 @@ controls available to zoom and rotate the camera:
     Shift-drag to pan left/right and up/down.
     Touch screen: pinch/extend to zoom, swipe or two-finger rotate.
 
-Currently, to re-run a VPython program in a Jupyter notebook you need to click the circular arrow icon to "restart the kernel" and then click the red-highlighted button, then click in the first cell, then click the run icon. Alternatively, if you insert "scene = canvas()" at the start of your program, you can rerun the program without restarting the kernel.
+Currently, to re-run a VPython program in a Jupyter notebook you need to click the circular arrow icon to "restart the kernel" and then click the red-highlighted button, then click in the first cell, then click the run icon. Alternatively, if you insert `scene = canvas()`` at the start of your program, you can rerun the program without restarting the kernel.
 
 Run example VPython programs: [![Binder](http://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/BruceSherwood/vpython-jupyter/7.4.7?filepath=index.ipynb)
 
+## Installation for developers from package source
+
+You should install Cython (`conda install cython` or `pip install cython`) so
+that the fast version of the vector class can be generated and compiled. You
+may also need to install a compiler (command line tools on Mac, community
+edition on Visual Studio on Windows).
+
+If you don't have a compilier vpython should still work, but code that
+generates a lot of vectors may run a little slower.
+
+To install vpython from source run this command from the source directory
+after you have downloaded it:
+
+```
+pip install -e .
+```
+
+The `-e` option installs the code with symbolic links so that change you make
+show up without needing to reinstall.
+
+If you also need the JupyterLab extension, please see the instructions
+in the `labextension` folder.
+
 ## vpython build status (for the vpython developers)
 
 [![Build Status](https://travis-ci.com/vpython/vpython-jupyter.svg?branch=master)](https://travis-ci.com/vpython/vpython-jupyter) [![Build status](https://ci.appveyor.com/api/projects/status/mb3y238y1eae7xnh?svg=true)](https://ci.appveyor.com/project/vpython/vpython-jupyter)

RELEASE.md

@@ -0,0 +1,41 @@
+# How to do a vpython release
+
+There are two things that need to be released:
+
++ The Python package `vpython-jupyter`
++ The JupyterLab extension called `vpython`
+
+## Releasing the Python package
+
+Versions for the Python package are generated using
+[`versioneer`](https://github.com/warner/python-versioneer). That means that
+to make a new release the first step is to generate a git tag with the release
+numbers.
+
+Release numbers should be in the format `X.Y.Z`, e.g. `7.4.2` or `7.5.0`.
+
+Currently, all of the build/upload of the releases is handled on Travis-CI and
+Appveyor, but in principle one could build the packages on local machines and
+upload them.
+
+Tagging the commit in GitHub or doing the tag locally and pushing it to GitHub
+will trigger the builds without any further action.
+
+If you want to build locally:
+
++ Build and upload the source distribution (once per release)
+    * `python setup.py sdist` -- generate the source distribution
+    * `twine upload dist/*.tar.gz` -- upload the generated distribution
++ Build and upload binary wheels (once per release *per platform*)
+    * `python setup.py wheel` -- generate binary distribution on the platform
+      on which you are running.
+    * `twine upload dist/*.whl` -- upload the generated distribution
++ Build the conda package (once per release *per platform*)
+    * `conda build vpython.recipe`
+    * `anaconda upload `*recipe_location* -- replace *recipe_location* with
+      the directory output by conda build.
+
+## Releasing the JupyterLab Extension
+
+Please see the instructions in the `labextension` folder for building and
+releasing the JupyterLab extension.