8000 rewrite installation doc · funature/pvlib-python@2d6c1a8 · GitHub
[go: up one dir, main page]
Skip to content 10000

Commit 2d6c1a8

Browse files
wholmgrenwholmgren
committed
rewrite installation doc
1 parent 003dc88 commit 2d6c1a8

File tree

2 files changed

+152
-49
lines changed

2 files changed

+152
-49
lines changed

‎docs/sphinx/source/_images/clonebutton.png

245 KB
Loading

‎docs/sphinx/source/installation.rst

Lines changed: 152 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,26 @@
33
Installation
44
============
55

6-
Installing pvlib-python is similar to installing most other scientific
7-
python packages. The instructions below describe how to install
8-
pvlib-python under a few different conditions. Most of the information
9-
on the `Pandas installation page
10-
<http://pandas.pydata.org/pandas-docs/stable/install.html>`_ is also
11-
applicable to pvlib-python.
6+
Installing pvlib-python ranges from trivial to difficult depending
7+
on your python experience, how you want to use pvlib, and your
8+
system configuration.
129

13-
If you have Python
14-
------------------
10+
**Do you already have Python and the NumPy and Pandas libraries?**
1511

16-
To obtain the most recent stable release of pvlib-python, use
17-
`conda <http://conda.pydata.org/docs/>`_ or `pip <https://pip.pypa.io>`_::
12+
If the answer to this is *No*, follow the :ref:`nopython` instructions
13+
to obtain the Anaconda Python distribution before proceeding.
1814

19-
conda install -c pvlib pvlib
15+
**Do you want to use the pvlib-python as-is, or do you want to be
16+
able to edit the source code?**
2017

21-
pip install pvlib
18+
If you want to use pvlib-python *as-is*, follow the simple
19+
:ref:`standardrelease` instructions.
2220

23-
If your system complains that you don't have access privileges or asks
24-
for a password then you're probably trying to install pvlib into your
25-
system's Python distribution. This is usually a bad idea and you should
26-
instead follow the :ref:`nopython` instructions below.
21+
If you want to be able to *edit the source code*, follow the
22+
:ref:`editablelibrary` instructions.
23+
24+
Installing pvlib-python is similar to installing most scientific python
25+
packages, so see the :ref:`references` section for further help.
2726

2827
.. _nopython:
2928

@@ -34,49 +33,153 @@ There are many ways to install Python on your system, but the Anaconda
3433
Scientific Python distribution provides by far the easiest way for new
3534
users to get started. Anaconda includes all of the popular libraries
3635
that you'll need for pvlib, including Pandas, NumPy, and SciPy.
37-
"Anaconda installs cleanly into a single directory, does not require
38-
Administrator or root privileges, does not affect other Python installs
39-
on your system, or interfere with OSX Frameworks." -Anaconda
40-
Documentation.
4136

42-
#. Install the full Anaconda Scientific Python distribution available
43-
`here <https://store.continuum.io/cshop/anaconda/>`_
44-
#. Install pvlib: ``conda install -c pvlib pvlib``
37+
Anaconda installs cleanly into a single directory, does not require
38+
Administrator or root privileges, does not affect other Python installs
39+
on your system, or interfere with OSX Frameworks. -- `The Anaconda
40+
Documentation <https://docs.continuum.io/anaconda/index>`_
41+
42+
#. **Install** the full Anaconda Scientific Python distribution available
43+
`at Continuum.io <https://store.continuum.io/cshop/anaconda/>`_
44+
45+
See the `Anaconda FAQ <http://docs.continuum.io/anaconda/faq.html>`_
46+
for more information.
47+
48+
49+
.. _standardrelease:
50+
51+
Install standard release
52+
------------------------
53+
54+
To obtain the most recent stable release of pvlib-python, use
55+
`conda <http://conda.pydata.org/docs/>`_ or `pip <https://pip.pypa.io>`_::
56+
57+
conda install -c pvlib pvlib
58+
59+
pip install pvlib
60+
61+
If your system complains that you don't have access privileges or asks
62+
for a password then you're probably trying to install pvlib into your
63+
system's Python distribution. This is usually a bad idea and you should
64+
follow the :ref:`nopython` instructions before installing pvlib.
65+
66+
You may still want to download the Python source code so that you can
67+
easily get all of the Jupyter Notebook tutorials. Either clone the `git
68+
repository <https://github.com/pvlib/pvlib-python>`_ or go to the
69+
`Releases page <https://github.com/pvlib/pvlib-python/releases>`_ to
70+
download the zip file of the most recent release. You can also use
71+
the nbviewer website to choose a tutorial to experiment with.
72+
Go to our `nbviewer tutorial page
73+
<http://nbviewer.jupyter.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/>`_
74+
75+
76+
.. _editablelibrary:
77+
78+
Install as an editable library
79+
------------------------------
80+
81+
Installing pvlib-python as an editable library involves 3 steps:
82+
83+
1. :ref:`obtainsource`
84+
2. :ref:`setupenvironment`
85+
3. :ref:`installsource`
86+
87+
None of these steps are particularly challenging, but they become
88+
more difficult when combined.
89+
With a little bit of practice the process will be fast and easy.
90+
Experienced users can easily execute these steps in less than a minute.
91+
You'll get there.
92+
93+
.. _obtainsource:
94+
95+
Obtain the source code
96+
~~~~~~~~~~~~~~~~~~~~~~
97+
98+
We will describe how to obtain the pvlib-python source code using
99+
the git/GitHub version control system. We encourage users to learn
100+
how to use these powerful tools, but we also recognize that they
101+
can be a substantial roadblock to getting started with pvlib-python.
102+
Therefore, you should know that you can download a zip file of
103+
the most recent development version of the source code by
104+
clicking on the **Download Zip** button on the right side of our
105+
`GitHub page <https://github.com/pvlib/pvlib-python>`_
106+
or download a zip file of any stable release from our
107+
`Releases page <https://github.com/pvlib/pvlib-python/releases>`_.
108+
109+
Follow these steps to obtain the library using git/GitHub:
110+
111+
#. **Download** the `GitHub Desktop <https://desktop.github.com>`_ application.
112+
#. **Fork** the pvlib-python project by clicking on the "Fork" button on
113+
the upper right corner of the
114+
`pvlib-python GitHub page <https://github.com/pvlib/pvlib-python>`_.
115+
#. **Clone** your fork to your computer using the GitHub Desktop application
116+
by clicking on the *Clone to Desktop* button on your fork's homepage.
117+
This button is circled in the image below.
118+
119+
.. image:: _images/clonebutton.png
45120

46-
If you have trouble, see the `Anaconda
47-
FAQ <http://docs.continuum.io/anaconda/faq.html>`_, Google your error
48-
messages, or make a new issue on our `Issues
49-
page <https://github.com/pvlib/pvlib-python/issues>`_.
121+
Please see GitHub's
122+
`Forking Projects <https://guides.github.com/activities/forking/>`_ and
123+
`Fork A Repo <https://help.github.com/articles/fork-a-repo/>`_ for
124+
more details.
50125

126+
.. _setupenvironment:
51127

52-
Working at the bleeding edge
53-
----------------------------
128+
Set up a virtual environment
129+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
54130

55131
We strongly recommend working in a `virtual environment
56132
<http://astropy.readthedocs.org/en/latest/development/workflow/
57-
virtual_pythons.html>`_ if you're going to use the development versions
58-
of the code. There are many ways to use virtual environments in Python,
59-
but Anaconda again provides the easiest solution:
133+
virtual_pythons.html>`_ if you're going to use an editable version
134+
of the library. You can skip this step if:
60135

61-
#. Create a new conda environment for pvlib and pre-install a
62-
handful of packages into the environment:
63-
``conda create --name pvlibdev python pandas scipy``
64-
#. Activate the new environment: ``source activate pvlibdev``
65-
#. Install the latest development version of pvlib:
136+
#. You already have Anaconda or another scientific Python distribution
137+
#. You don't mind polluting your Python installation with your
138+
development version of pvlib.
139+
#. You don't want to work with multiple versions of pvlib.
66140

67-
#. If you don't plan to modify the source-code:
68-
``pip install git+https://github.com/pvlib/pvlib-python.git``
69-
#. If you do plan to modify the source code:
70-
Use the GitHub GUI application or git command-line tool to
71-
clone this repository to your computer, then navigate your
72-
command-line to the top-level pvlib-python directory,
73-
then ``pip install -e .``
141+
There are many ways to use virtual environments in Python,
142+
but Anaconda again provides the easiest solution. These are often
143+
referred to as *conda environments*, but they're the same for our purposes.
74144

75-
#. You may also consider installing additional packages into your
76-
development environment:
77-
``conda install jupyter ipython seaborn nose flake8``
145+
#. **Create** a new conda environment for pvlib and pre-install
146+
the required packages into the environment:
147+
``conda create --name pvlibdev python pandas scipy``
148+
#. **Activate** the new conda environment: ``source activate pvlibdev``
149+
#. **Install** additional packages into your development environment:
150+
``conda install jupyter ipython matplotlib seaborn nose flake8``
78151

79152
The `conda documentation
80153
<http://conda.pydata.org/docs/using/index.html>`_ has more information
81-
on how to use virtual environments. You can also add ``-h`` to most
82-
conda commands to get help (e.g. ``conda -h`` or ``conda env -h``)
154+
on how to use conda virtual environments. You can also add ``-h`` to most
155+
pip and conda commands to get help (e.g. ``conda -h`` or ``conda env -h``)
156+
157+
.. _installsource:
158+
159+
Install the source code
160+
~~~~~~~~~~~~~~~~~~~~~~~
161+
162+
Good news -- installing the source code is the easiest part!
163+
164+
#. In your terminal or shell, **navigate** to the top-level
165+
pvlib-python directory.
166+
#. **Install** pvlib-python in "development mode" by running
167+
``pip install -e .``
168+
169+
170+
.. _references:
171+
172+
References
173+
----------
174+
175+
Here are a few recommended references for installing Python packages:
176+
177+
* `The Pandas installation page
178+
<http://pandas.pydata.org/pandas-docs/stable/install.html>`_
179+
* `python4astronomers Modules, Packages, and all that
180+
<https://python4astronomers.github.io/installation/packages.html>`_
181+
* `Python Packaging User Guide
182+
<http://python-packaging-user-guide.readthedocs.org/en/latest/>`_
183+
* `Conda User Guide
184+
<http://conda.pydata.org/docs/index.html>`_
185+

0 commit comments

Comments
 (0)
0