Skip to content

rewrite installation doc #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wholmgren merged 3 commits into from
Mar 21, 2016
Merged

rewrite installation doc #138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2d6c1a8
rewrite installation doc
wholmgren Mar 19, 2016
f63c152
add path hints, test, reload, git refs
wholmgren Mar 21, 2016
c7cb422
clarify that pvlib needs to be installed after anaconda
wholmgren Mar 21, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/sphinx/source/_images/clonebutton.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
239 changes: 190 additions & 49 deletions docs/sphinx/source/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

@dacoex dacoex Mar 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are also automated Ubuntu builds.
But since many of the ubuntu packages are quite outdated (e.g. jupyter) this may not be relevent. Once situation changes at their end, we can update the text here.

packages, so see the :ref:`references` section for further help.

.. _nopython:

Expand All @@ -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
Copy link
Contributor

@dacoex dacoex Mar 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this hint. It appears this has improved in the last months! I was not able to install as non-admin before.

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.

Copy link
Contributor

@alorenzo175 alorenzo175 Mar 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should also say that once Anaconda is installed, pvlib stills needs to be installed via one of the methods below.

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

Copy link
Contributor

@dacoex dacoex Mar 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest:

conda install -c pvlib pvlib
# or, if not using conda, e.g. on WinPython:
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``
Copy link
Contributor

@dacoex dacoex Mar 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is even more understandable than upsteam!

I never understood fromCreate an environment
conda create --name snowflakes biopython
What? Nicely written.

#. **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
Copy link
Contributor

@dacoex dacoex Mar 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I sometimes do not understand with development mode and the git branching concept where all branches are the same directory but change with checkout command:

How do I keep the symlinks the editable working even if I work on different branches:

Say I work on 1 feature so git checkout -b pvlib_newfeature. How do I prevent this editable environment from getting broken?
Or should I, in this case, create a new environment for each branch.with a separate clone in another directory?

Note: this is not a flaw of the text. Just a point doubt for a non-wizzard git user...

So a link to a nice external page that explains how to integrate different git branches of a library with editable installs would be useful. Thanks.

Copy link
Contributor

@jforbess jforbess Mar 21, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am hoping to review this more in depth, (I read the document somewhat
quickly, and agree with DaCoEx that some of the explanations are even
better than the standard docs), but I wanted to mention that people might
need some help wrapping their head around git, generally, and this document
seems helpful to me with the amount of version control understanding I
started with (advanced beginner):
http://betterexplained.com/articles/aha-moments-when-learning-git/

On Mon, Mar 21, 2016 at 5:55 AM, DaCoEx [email protected] wrote:

In docs/sphinx/source/installation.rst
#138 (comment):

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!
+
+#. In your terminal or shell, navigate to the top-level

  • pvlib-python directory.
    +#. Install pvlib-python in "development mode" by running

What I sometimes do not understand with development mode and the git
branching concept where all branches are the same directory but change with
checkout command:

How do I keep the symlinks the editable working even if I work on
different branches:

Say I work on 1 feature so git checkout -b pvlib_newfeature. How do I
prevent this editable environment from getting broken?
Or should I, in this case, create a new environment for each branch.with a
separate clone in another directory?

Note: this is not a flaw of the text. so a link to a nice page that
explains this would be useful.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
https://github.com/pvlib/pvlib-python/pull/138/files/2d6c1a83ab7debbb9b71e8aab9c9929898c2739e#r56816913

``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/>`_