Merge pull request #135 from wholmgren/contributing

documentation updates

Author: wholmgren

docs/sphinx/source/comparison_pvlib_matlab.rst

@@ -1,66 +1,80 @@
 .. _comparison_pvlib_matlab:
 
 ****************************
-Comparison with PVLIB_MATLAB
+Comparison with PVLIB MATLAB
 ****************************
 
-This document is under construction.
-Please see our 
-`PVSC 2014 paper <http://energy.sandia.gov/wp/wp-content/gallery/uploads/PV_LIB_Python_final_SAND2014-18444C.pdf>`_
-and
-`PVSC 2015 abstract <https://github.com/UARENForecasting/pvlib-pvsc2015/blob/master/pvlib_pvsc_42.pdf?raw=true>`_ 
-for more information.
+PVLIB was originally developed as a library for MATLAB at Sandia
+National Lab, and Sandia remains the official maintainer of the MATLAB
+library. Sandia supported the initial Python port and
+then released further project maintenance and development to the
+`pvlib-python maintainers <https://github.com/orgs/pvlib/people>`_.
 
-The pvlib-python license is BSD 3-clause,
-the PVLIB\_MATLAB license is ??.
+The pvlib-python maintainers collaborate with the PVLIB MATLAB
+maintainers but operate independently. We'd all like to keep the core
+functionality of the Python and MATLAB projects synchronized, but this
+will require the efforts of the larger pvlib-python community, not just
+the maintainers. Therefore, do not expect feature parity between the
+libaries, only similarity.
 
-We want to keep developing the core functionality and algorithms 
-of the Python and MATLAB projects roughly in parallel, 
-but we're not making any promises at this point.
-The PVLIB\_MATLAB and pvlib-python projects are currently developed 
-by different teams that do not regularly work together. 
-We hope to grow this collaboration in the future.
-Do not expect feature parity between the libaries, only similarity.
+Major differences
+~~~~~~~~~~~~~~~~~
 
-Here are some of the major differences between the latest pvlib-python build 
-and the original Sandia PVLIB\_Python project, but many of these
-comments apply to the difference between pvlib-python and PVLIB\_MATLAB.
+* pvlib-python uses git version control to track all changes
+  to the code. A summary of changes is included in the whatsnew file
+  for each release. PVLIB MATLAB documents changes in Changelog.docx
+* pvlib-python has a comprehensive test suite, whereas PVLIB MATLAB does
+  not have a test suite at all. Specifically, pvlib-python
 
+    * Uses TravisCI for automated testing on Linux.
+    * Uses Appveyor for automated testing on Windows.
+    * Uses Coveralls to measure test coverage.
 
-Library wide changes
-~~~~~~~~~~~~~~~~~~~~
+* Using readthedocs for automated documentation building and hosting.
+* Removed ``pvl_`` from module/function names.
+* Consolidated similar functions into topical modules.
+  For example, functions from ``pvl_clearsky_ineichen.m`` and
+  ``pvl_clearsky_haurwitz.m`` have been consolidated into ``clearsky.py``.
+* PVLIB MATLAB uses ``location`` structs as the input to some functions.
+  pvlib-python just uses the lat, lon, etc. as inputs to the functions.
+  Furthermore, pvlib-python replaces the structs with classes, and these classes
+  have methods, such as :py:func:`~pvlib.location.Location.get_solarposition`,
+  that automatically reference the appropriate data.
+  See :ref:`modeling-paradigms` for more information.
+* pvlib-python implements a handful of class designed to simplify the
+  PV modeling process. These include :py:class:`~pvlib.location.Location`,
+  :py:class:`~pvlib.pvsystem.PVSystem`,
+  :py:class:`~pvlib.pvsystem.LocalizedPVSystem`,
+  :py:class:`~pvlib.tracking.SingleAxisTracker`,
+  and
+  :py:class:`~pvlib.modelchain.ModelChain`.
 
-* Remove ``pvl_`` from module names.
-* Consolidation of similar modules. For example, functions from ``pvl_clearsky_ineichen.py`` and ``pvl_clearsky_haurwitz.py`` have been consolidated into ``clearsky.py``. 
-* Removed ``Vars=Locals(); Expect...; var=pvl\_tools.Parse(Vars,Expect);`` pattern. Very few tests of input validitity remain. Garbage in, garbage or ``nan`` out.
-* Removing unnecssary and sometimes undesired behavior such as setting maximum zenith=90 or airmass=0. Instead, we make extensive use of ``nan`` values.
-* Changing function and module names so that they do not conflict.
-* Added ``/pvlib/data`` for lookup tables, test, and tutorial data.
+Other differences
+~~~~~~~~~~~~~~~~~
 
-
-More specific changes
-~~~~~~~~~~~~~~~~~~~~~
-
-* Add PyEphem option to solar position calculations. 
-* ``irradiance.py`` has more AOI, projection, and irradiance sum and calculation functions
-* Locations are now ``pvlib.location.Location`` objects, not structs.
-* Specify time zones using a string from the standard IANA Time Zone Database naming conventions or using a pytz.timezone instead of an integer GMT offset. We may add dateutils support in the future.
-* ``clearsky.ineichen`` supports interpolating monthly Linke Turbidities to daily resolution.
+* Very few tests of input validitity exist in the Python code.
+  We believe that the vast majority of these tests were not necessary.
+  We also make use of Python's robust support for raising and catching
+  exceptions.
+* Removed unnecessary and sometimes undesired behavior such as setting
+  maximum zenith=90 or airmass=0. Instead, we make extensive use of
+  ``nan`` values in returned arrays.
+* Implemented the NREL solar position calculation algorithm.
+  Also added a PyEphem option to solar position calculations.
+* Specify time zones using a string from the standard IANA Time Zone
+  Database naming conventions or using a pytz.timezone instead of an
+  integer GMT offset.
+* ``clearsky.ineichen`` supports interpolating monthly
+  Linke Turbidities to daily resolution.
 * Instead of requiring effective irradiance as an input, ``pvsystem.sapm``
   calculates and returns it based on input POA irradiance, AM, and AOI.
+* pvlib-python does not come with as much example data.
+* pvlib-python does not currently implement as many algorithms as
+  PVLIB MATLAB.
 
 Documentation
 ~~~~~~~~~~~~~
 
-* Using readthedocs for documentation hosting.
-* Many typos and formatting errors corrected.
-* Documentation source code and tutorials live in ``/`` rather than ``/pvlib/docs``.
-* Additional tutorials in ``/docs/tutorials``.
-
-Testing
-~~~~~~~
-
-* Tests are cleaner and more thorough. They are still no where near complete.
-* Using Coveralls to measure test coverage. 
-* Using TravisCI for automated testing.
-* Using ``nosetests`` for more concise test code. 
+* Using Sphinx to build the documentation,
+  including dynamically created inline examples.
+* Additional Jupyter tutorials in ``/docs/tutorials``.

docs/sphinx/source/conf.py

@@ -50,6 +50,7 @@ def __getattr__(cls, name):
     'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
     'numpydoc',
     'sphinx.ext.autosummary',
@@ -77,7 +78,7 @@ def __getattr__(cls, name):
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 # Get the version from the version file
-version_file = os.path.join(os.path.dirname(__file__), 
+version_file = os.path.join(os.path.dirname(__file__),
                             '../../../pvlib/version.py')
 with open(version_file, 'r') as f:
     exec(f.read())
@@ -301,3 +302,11 @@ def __getattr__(cls, name):
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3.5/', None),
+    'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
+    'numpy': ('http://docs.scipy.org/doc/numpy/', None),
+}
+

docs/sphinx/source/contributing.rst

@@ -0,0 +1,89 @@
+.. _contributing:
+
+Contributing
+============
+
+Encouraging more people to help develop pvlib-python is essential to our
+success. Therefore, we want to make it easy and rewarding for you to
+contribute.
+
+
+Easy ways to contribute
+-----------------------
+
+Here are a few ideas for you can contribute, even if you are new to
+pvlib-python, git, or Python:
+
+* Make `GitHub issues <https://github.com/pvlib/pvlib-python/issues>`_
+  and contribute to the conversation about how to resolve them.
+* Read issues and pull requests that other people created and
+  contribute to the conversation about how to resolve them.
+* Improve the documentation and the unit tests.
+* Improve the IPython/Jupyter Notebook tutorials or write new ones that
+  demonstrate how to use pvlib-python in your area of expertise.
+* If you have MATLAB experience, you can help us keep pvlib-python
+  up to date with PVLIB_MATLAB or help us develop common unit tests.
+  For more, see `Issue #2 <https://github.com/pvlib/pvlib-python/issues/2>`_
+  and `Issue #3 <https://github.com/pvlib/pvlib-python/issues/3>`_.
+* Tell your friends and colleagues about pvlib-python.
+* Add your project to our
+  `Projects and publications that use pvlib-python wiki
+  <https://github.com/pvlib/pvlib-python/wiki/Projects-and-publications-
+  that-use-pvlib-python>`_.
+
+
+How to contribute new code
+--------------------------
+
+Contributors to pvlib-python use GitHub's pull requests to add/modify
+its source code. The GitHub pull request process can be intimidating for
+new users, but you'll find that it becomes straightforward once you use
+it a few times. Please let us know if you get stuck at any point in the
+process. Here's an outline of the process:
+
+#. Create a GitHub issue and get initial feedback from users and
+   maintainers. If the issue is a bug report, please include the
+   code needed to reproduce the problem.
+#. Obtain the latest version of pvlib-python: Fork the pvlib-python
+   project to your GitHub account, ``git clone`` your fork to your computer.
+#. Make some or all of your changes/additions and ``git commit`` them to
+   your local repository.
+#. Share your changes with us via a pull request: ``git push`` your
+   local changes to your GitHub fork, then go to GitHub make a pull
+   request.
+
+The Pandas project maintains an excellent `contributing page
+<https://github.com/pydata/pandas/wiki/Contributing>`_ that goes into
+detail on each of these steps. Also see GitHub's `Set Up Git
+<https://help.github.com/articles/set-up-git/>`_ and `Using Pull
+Requests <https://help.github.com/articles/using-pull-requests/>`_.
+
+Note that you do not need to make all of your changes before creating a
+pull request. Your pull requests will automatically be updated when you
+commit new changes and push them to GitHub. This gives everybody an easy
+way to comment on the code and can make the process more efficient.
+
+We strongly recommend using virtual environments for development.
+Virtual environments make it trivial to switch between different
+versions of software. This `astropy guide
+<http://astropy.readthedocs.org/en/latest/development/workflow/
+virtual_pythons.html>`_ is a good reference for virtual environments. If
+this is your first pull request, don't worry about using a virtual
+environment.
+
+You must include documentation and unit tests for any new or improved
+code. We can provide help and advice on this after you start the pull
+request.
+
+The maintainers will follow same procedures, rather than making direct
+commits to the main repo. Exceptions may be made for extremely minor
+changes, such as fixing documentation typos.
+
+
+This documentation
+------------------
+If this documentation is unclear, help us improve it! Consider looking
+at `IPython <https://github.com/ipython/ipython/wiki/Dev:-Index>`_,
+`pandas <https://github.com/pydata/pandas/wiki>`_, and
+`Sandia-Labs/PVLIB_Python#33 <https://github.com/Sandia-Labs/
+PVLIB_Python/issues/33>`_ for inspiration.

docs/sphinx/source/index.rst

@@ -1,67 +1,78 @@
-Welcome to pvlib-python's documentation!
+pvlib-python
 ========================================
 
-pvlib-python provides a set of documented functions for simulating 
-the performance of photovoltaic energy systems. 
-The toolbox was originally developed in MATLAB at 
-Sandia National Laboratories and it implements many of the 
-models and methods developed at the Labs. 
-More information on Sandia Labs PV performance modeling programs 
-can be found at https://pvpmc.sandia.gov/.
-
-The source code for pvlib-python is hosted on 
-`github <https://github.com/pvlib/pvlib-python>`_.
-
-The github page also contains a valuable
-`wiki <https://github.com/pvlib/pvlib-python/wiki>`_
-with information on how you can contribute to pvlib-python development!
-
-Please see the links above for details on the status of the pvlib-python
-project. We are at an early stage in the development of this project,
-so expect to see significant API changes in the next few releases.
-
-This documentation focuses on providing a reference for all of 
-the modules and functions available in pvlib-python.
-For examples of how to use pvlib-python, please see the
-`tutorials <http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/>`_.
-Some of the tutorials were written with older
-versions of pvlib-python and we would greatly appreciate your
-help updating them!
-
-.. note::
-
-   This documentation assumes general familiarity with
-   Python, NumPy, and Pandas. Google searches will yield many
-   excellent tutorials for these packages. 
-   
-Please see our 
-`PVSC 2014 paper <http://energy.sandia.gov/wp/wp-content/gallery/uploads/PV_LIB_Python_final_SAND2014-18444C.pdf>`_
-and
-`PVSC 2015 paper <https://github.com/pvlib/pvsc2015/blob/master/pvlib_pvsc_42.pdf>`_ 
-(and the `notebook to reproduce the figures <http://nbviewer.ipython.org/github/pvlib/pvsc2015/blob/master/paper.ipynb>`_) for more information.
-
-The GitHub wiki also has a page on `Projects and publications that use pvlib python <https://github.com/pvlib/pvlib-python/wiki/Projects-and-publications-that-use-pvlib-python>`_ for inspiration and listing of your application.
-
-There is a :ref:`variable naming convention <variables_style_rules>` to ensure consistency throughout the library.
-
-Installation
-============
-
-1. Follow Pandas' 
-   `instructions <http://pandas.pydata.org/pandas-docs/stable/install.html>`_
-   for installing the scientific python stack, including ``pip``.
-#. ``pip install pvlib-python``
+pvlib-python provides a set of documented functions for simulating the
+performance of photovoltaic energy systems. The toolbox was originally
+developed in MATLAB at Sandia National Laboratories and it implements
+many of the models and methods developed at the Labs. More information
+on Sandia Labs PV performance modeling programs can be found at
+https://pvpmc.sandia.gov/.
+
+The source code for pvlib-python is hosted on `github
+<https://github.com/pvlib/pvlib-python>`_.
+
+Please see the :ref:`installation` page for installation help.
+
+For examples of how to use pvlib-python, please see
+:ref:`package_overview` and our `Jupyter Notebook tutorials
+<http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/
+tutorials/>`_. The documentation assumes general familiarity with
+Python, NumPy, and Pandas. Google searches will yield many
+excellent tutorials for these packages.
+
+The pvlib-python GitHub wiki has a `Projects and publications that use
+pvlib python
+<https://github.com/pvlib/pvlib-python/wiki/Projects-and-publications-
+that-use-pvlib-python>`_ page for inspiration and listing of your
+application.
+
+There is a :ref:`variable naming convention <variables_style_rules>` to
+ensure consistency throughout the library.
+
+Citing pvlib-python
+===================
+
+Many of the contributors to pvlib-python work in institutions where
+citation metrics are used in performance or career evaluations. If you
+use pvlib-python in a published work, please cite the most appropriate
+of:
+
+* J. S. Stein, “The photovoltaic performance modeling
+  collaborative (PVPMC),” in Photovoltaic Specialists Conference, 2012.
+* R.W. Andrews, J.S. Stein, C. Hansen, and D. Riley, “Introduction
+  to the open source pvlib for python photovoltaic system
+  modelling package,” in 40th IEEE Photovoltaic Specialist
+  Conference, 2014.
+  (`paper
+  <http://energy.sandia.gov/wp/wp-content/gallery/uploads/PV_LIB_Python_final_SAND2014-18444C.pdf>`_)
+* W.F. Holmgren, R.W. Andrews, A.T. Lorenzo, and J.S. Stein,
+  “PVLIB Python 2015,” in 42nd Photovoltaic Specialists Conference, 2015.
+  (`paper
+  <https://github.com/pvlib/pvsc2015/blob/master/pvlib_pvsc_42.pdf>`_ and
+  the `notebook to reproduce the figures
+  <http://nbviewer.ipython.org/github/pvlib/pvsc2015/blob/master/paper.ipynb>`_)
+* J.S. Stein, W.F. Holmgren, J. Forbess, and C.W. Hansen,
+  "PVLIB: Open Source Photovoltaic Performance Modeling Functions
+  for Matlab and Python," in 43rd Photovoltaic Specialists Conference, 2016.
+* W.F. Holmgren and D.G. Groenendyk,
+  "An Open Source Solar Power Forecasting Tool Using PVLIB-Python,"
+  in 43rd Photovoltaic Specialists Conference, 2016.
+
+Specific released versions of pvlib-python can be cited using their
+`Zenodo DOI <https://zenodo.org/search?ln=en&p=pvlib&action_search=>`_.
 
 
 Contents
 ========
 
 .. toctree::
    :maxdepth: 2
-   
-   self
+
    package_overview
    whatsnew
+   installation
+   contributing
+   timetimezones
    modules
    classes
    comparison_pvlib_matlab
@@ -72,6 +83,4 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-