Merge pull request #138 from wholmgren/installdocs

rewrite installation doc

Author: wholmgren

docs/sphinx/source/_images/clonebutton.png

@@ -3,27 +3,26 @@
 Installation
 ============
 
-Installing pvlib-python is similar to installing most other scientific
-python packages. The instructions below describe how to install
-pvlib-python under a few different conditions. Most of the information
-on the `Pandas installation page
-<http://pandas.pydata.org/pandas-docs/stable/install.html>`_ is also
-applicable to pvlib-python.
+Installing pvlib-python ranges from trivial to difficult depending
+on your python experience, how you want to use pvlib, and your
+system configuration.
 
-If you have Python
-------------------
+**Do you already have Python and the NumPy and Pandas libraries?**
 
-To obtain the most recent stable release of pvlib-python, use
-`conda <http://conda.pydata.org/docs/>`_ or `pip <https://pip.pypa.io>`_::
+    If the answer to this is *No*, follow the :ref:`nopython` instructions
+    to obtain the Anaconda Python distribution before proceeding.
 
-    conda install -c pvlib pvlib
+**Do you want to use the pvlib-python as-is, or do you want to be
+able to edit the source code?**
 
-    pip install pvlib
+    If you want to use pvlib-python *as-is*, follow the simple
+    :ref:`standardrelease` instructions.
 
-If your system complains that you don't have access privileges or asks
-for a password then you're probably trying to install pvlib into your
-system's Python distribution. This is usually a bad idea and you should
-instead follow the :ref:`nopython` instructions below.
+    If you want to be able to *edit the source code*, follow the
+    :ref:`editablelibrary` instructions.
+
+Installing pvlib-python is similar to installing most scientific python
+packages, so see the :ref:`references` section for further help.
 
 .. _nopython:
 
@@ -34,49 +33,191 @@ There are many ways to install Python on your system, but the Anaconda
 Scientific Python distribution provides by far the easiest way for new
 users to get started. Anaconda includes all of the popular libraries
 that you'll need for pvlib, including Pandas, NumPy, and SciPy.
-"Anaconda installs cleanly into a single directory, does not require
-Administrator or root privileges, does not affect other Python installs
-on your system, or interfere with OSX Frameworks." -Anaconda
-Documentation.
 
-#. Install the full Anaconda Scientific Python distribution available
-   `here <https://store.continuum.io/cshop/anaconda/>`_
-#. Install pvlib: ``conda install -c pvlib pvlib``
+    Anaconda installs cleanly into a single directory, does not require
+    Administrator or root privileges, does not affect other Python installs
+    on your system, or interfere with OSX Frameworks. -- `The Anaconda
+    Documentation <https://docs.continuum.io/anaconda/index>`_
+
+#. **Install** the full Anaconda Scientific Python distribution available
+   `at Continuum.io <https://store.continuum.io/cshop/anaconda/>`_
+
+See the `Anaconda FAQ <http://docs.continuum.io/anaconda/faq.html>`_
+for more information.
+
+You can now install pvlib-python by one of the methods below.
+
+
+.. _standardrelease:
+
+Install standard release
+------------------------
+
+To install the most recent stable release of pvlib-python in a
+non-editable way, use `conda <http://conda.pydata.org/docs/>`_
+(recommended if you use the Anaconda Python distribution) or `pip
+<https://pip.pypa.io>`_ (works with any Python distribution)::
+
+    conda install -c pvlib pvlib
+
+    pip install pvlib
+
+If your system complains that you don't have access privileges or asks
+for a password then you're probably trying to install pvlib into your
+system's Python distribution. This is usually a bad idea and you should
+follow the :ref:`nopython` instructions before installing pvlib.
+
+You may still want to download the Python source code so that you can
+easily get all of the Jupyter Notebook tutorials. Either clone the `git
+repository <https://github.com/pvlib/pvlib-python>`_ or go to the
+`Releases page <https://github.com/pvlib/pvlib-python/releases>`_ to
+download the zip file of the most recent release. You can also use the
+nbviewer website to choose a tutorial to experiment with. Go to our
+`nbviewer tutorial page
+<http://nbviewer.jupyter.org/github/pvlib/pvlib-python/tree/master/docs/
+tutorials/>`_.
+
+
+.. _editablelibrary:
+
+Install as an editable library
+------------------------------
+
+Installing pvlib-python as an editable library involves 3 steps:
+
+1. :ref:`obtainsource`
+2. :ref:`setupenvironment`
+3. :ref:`installsource`
+
+None of these steps are particularly challenging, but they become
+more difficult when combined.
+With a little bit of practice the process will be fast and easy.
+Experienced users can easily execute these steps in less than a minute.
+You'll get there.
 
-If you have trouble, see the `Anaconda
-FAQ <http://docs.continuum.io/anaconda/faq.html>`_, Google your error
-messages, or make a new issue on our `Issues
-page <https://github.com/pvlib/pvlib-python/issues>`_.
+.. _obtainsource:
 
+Obtain the source code
+~~~~~~~~~~~~~~~~~~~~~~
 
-Working at the bleeding edge
-----------------------------
+We will briefly describe how to obtain the pvlib-python source code
+using the git/GitHub version control system. We strongly encourage users
+to learn how to use these powerful tools (see the :ref:`references`!),
+but we also recognize that they can be a substantial roadblock to
+getting started with pvlib-python. Therefore, you should know that you
+can download a zip file of the most recent development version of the
+source code by clicking on the **Download Zip** button on the right side
+of our `GitHub page <https://github.com/pvlib/pvlib-python>`_ or
+download a zip file of any stable release from our `Releases page
+<https://github.com/pvlib/pvlib-python/releases>`_.
+
+Follow these steps to obtain the library using git/GitHub:
+
+#. **Download** the `GitHub Desktop <https://desktop.github.com>`_ application.
+#. **Fork** the pvlib-python project by clicking on the "Fork" button on
+   the upper right corner of the
+   `pvlib-python GitHub page <https://github.com/pvlib/pvlib-python>`_.
+#. **Clone** your fork to your computer using the GitHub Desktop application
+   by clicking on the *Clone to Desktop* button on your fork's homepage.
+   This button is circled in the image below. Remember the system path that
+   you clone the library to.
+
+.. image:: _images/clonebutton.png
+
+Please see GitHub's
+`Forking Projects <https://guides.github.com/activities/forking/>`_,
+`Fork A Repo <https://help.github.com/articles/fork-a-repo/>`_,
+and the `git-scm <https://git-scm.com/documentation>`_ for
+more details.
+
+.. _setupenvironment:
+
+Set up a virtual environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We strongly recommend working in a `virtual environment
 <http://astropy.readthedocs.org/en/latest/development/workflow/
-virtual_pythons.html>`_ if you're going to use the development versions
-of the code. There are many ways to use virtual environments in Python,
-but Anaconda again provides the easiest solution:
+virtual_pythons.html>`_ if you're going to use an editable version
+of the library. You can skip this step if:
 
-#. Create a new conda environment for pvlib and pre-install a
-   handful of packages into the environment:
-   ``conda create --name pvlibdev python pandas scipy``
-#. Activate the new environment: ``source activate pvlibdev``
-#. Install the latest development version of pvlib:
+#. You already have Anaconda or another scientific Python distribution
+#. You don't mind polluting your Python installation with your
+   development version of pvlib.
+#. You don't want to work with multiple versions of pvlib.
 
-  #. If you don't plan to modify the source-code:
-     ``pip install git+https://github.com/pvlib/pvlib-python.git``
-  #. If you do plan to modify the source code:
-     Use the GitHub GUI application or git command-line tool to
-     clone this repository to your computer, then navigate your
-     command-line to the top-level pvlib-python directory,
-     then ``pip install -e .``
+There are many ways to use virtual environments in Python,
+but Anaconda again provides the easiest solution. These are often
+referred to as *conda environments*, but they're the same for our purposes.
 
-#. You may also consider installing additional packages into your
-   development environment:
-   ``conda install jupyter ipython seaborn nose flake8``
+#. **Create** a new conda environment for pvlib and pre-install
+   the required packages into the environment:
+   ``conda create --name pvlibdev python pandas scipy``
+#. **Activate** the new conda environment: ``source activate pvlibdev``
+#. **Install** additional packages into your development environment:
+   ``conda install jupyter ipython matplotlib seaborn nose flake8``
 
 The `conda documentation
 <http://conda.pydata.org/docs/using/index.html>`_ has more information
-on how to use virtual environments. You can also add ``-h`` to most
-conda commands to get help (e.g. ``conda -h`` or ``conda env -h``)
+on how to use conda virtual environments. You can also add ``-h`` to most
+pip and conda commands to get help (e.g. ``conda -h`` or ``conda env -h``)
+
+.. _installsource:
+
+Install the source code
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Good news -- installing the source code is the easiest part!
+With your conda/virtual environment still active...
+
+#. **Install** pvlib-python in "development mode" by running
+   ``pip install -e /path/to/your/pvlib-python``.
+   You remember this path from the clone step, right? It's probably
+   something like ``C:\Users\%USER%\Documents\GitHub\pvlib-python``
+   (Windows) or ``/Users/%USER%/Documents/pvlib-python`` (Mac).
+#. **Test** your installation by running ``python -c 'import pvlib'``.
+   You're good to go if it returns without an exception.
+
+The version of pvlib-python that is on that path is now available
+as an installed package inside your conda/virtual environment.
+
+Any changes that you make to this pvlib-python will be available inside
+your environment. If you run a git checkout, branch, or pull command the
+result will be applied to your pvlib-python installation. This
+is great for development. Note, however, that you will need to use
+Python's ``reload`` function (`python 2
+<https://docs.python.org/2/library/functions.html#reload>`_, `python 3
+<https://docs.python.org/3/library/importlib.html#importlib.reload>`_)
+if you make changes to pvlib during an interactive Python
+session (including a Jupyter notebook). Restarting the Python
+interpreter will also work.
+
+Remember to ``source activate pvlibdev`` (or whatever you named your
+environment) when you start a new shell or terminal.
+
+.. _references:
+
+References
+----------
+
+Here are a few recommended references for installing Python packages:
+
+* `The Pandas installation page
+  <http://pandas.pydata.org/pandas-docs/stable/install.html>`_
+* `python4astronomers Modules, Packages, and all that
+  <https://python4astronomers.github.io/installation/packages.html>`_
+* `Python Packaging User Guide
+  <http://python-packaging-user-guide.readthedocs.org/en/latest/>`_
+* `Conda User Guide
+  <http://conda.pydata.org/docs/index.html>`_
+
+Here are a few recommended references for git and GitHub:
+
+* `The git documentation <https://git-scm.com/doc>`_:
+  detailed explanations, videos, more links, and cheat sheets. Go here first!
+* `Forking Projects <https://guides.github.com/activities/forking/>`_
+* `Fork A Repo <https://help.github.com/articles/fork-a-repo/>`_
+* `Cloning a repository
+  <https://help.github.com/articles/cloning-a-repository/>`_
+* `Aha! Moments When Learning Git
+  <http://betterexplained.com/articles/aha-moments-when-learning-git/>`_
+