update contributing documentation, pr template (#818)

* update contributing documentation

* update pr template

* add links to installation [skip ci]

* move sentence, add link

Author: wholmgren

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,19 +1,12 @@
-pvlib python pull request guidelines
-====================================
-
-Thank you for your contribution to pvlib python! You may delete all of these instructions except for the list below.
-
-You may submit a pull request with your code at any stage of completion.
-
-The following items must be addressed before the code can be merged. Please don't hesitate to ask for help if you're unsure of how to accomplish any of the items below:
-
- - [ ] Closes issue #xxxx
- - [ ] I am familiar with the [contributing guidelines](http://pvlib-python.readthedocs.io/en/latest/contributing.html).
- - [ ] Fully tested. Added and/or modified tests to ensure correct behavior for all reasonable inputs. Tests (usually) must pass on the TravisCI and Appveyor testing services.
- - [ ] Updates entries to `docs/sphinx/source/api.rst` for API changes.
- - [ ] Adds description and name entries in the appropriate `docs/sphinx/source/whatsnew` file for all changes.
- - [ ] Code quality and style is sufficient. Passes LGTM and SticklerCI checks.
- - [ ] New code is fully documented. Includes sphinx/numpydoc compliant docstrings and comments in the code where necessary.
+<!-- Thank you for your contribution! The following items must be addressed before the code can be merged. Please don't hesitate to ask for help if you're unsure of how to accomplish any of the items. Feel free to remove checklist items that are not relevant to your change. -->
+
+ - [ ] Closes #xxxx
+ - [ ] I am familiar with the [contributing guidelines](https://pvlib-python.readthedocs.io/en/latest/contributing.html)
+ - [ ] Tests added
+ - [ ] Updates entries to [`docs/sphinx/source/api.rst`](https://github.com/pvlib/pvlib-python/blob/master/docs/sphinx/source/api.rst) for API changes.
+ - [ ] Adds description and name entries in the appropriate "what's new" file in [`docs/sphinx/source/whatsnew`](https://github.com/pvlib/pvlib-python/tree/master/docs/sphinx/source/whatsnew) for all changes. Includes link to the GitHub Issue with `` :issue:`num` `` or this Pull Request with `` :pull:`num` ``. Includes contributor name and/or GitHub username (link with `` :ghuser:`user` ``).
+ - [ ] New code is fully documented. Includes [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) compliant docstrings, examples, and comments where necessary.
  - [ ] Pull request is nearly complete and ready for detailed review.
+ - [ ] Maintainer: Appropriate GitHub Labels and Milestone are assigned to the Pull Request and linked Issue.
 
-Brief description of the problem and proposed solution (if not already fully described in the issue linked to above):
+<!-- Brief description of the problem and proposed solution (if not already fully described in the issue linked to above): -->

docs/sphinx/source/conf.py

@@ -266,12 +266,13 @@ def setup(app):
 #latex_domain_indices = True
 
 # extlinks alias
-extlinks = {'issue': ('https://github.com/pvlib/pvlib-python/issues/%s',
-                      'GH'),
-            'wiki': ('https://github.com/pvlib/pvlib-python/wiki/%s',
-                     'wiki '),
-            'doi': ('http://dx.doi.org/%s', 'DOI: '),
-            'ghuser': ('https://github.com/%s', '@')}
+extlinks = {
+    'issue': ('https://github.com/pvlib/pvlib-python/issues/%s', 'GH'),
+    'pull': ('https://github.com/pvlib/pvlib-python/pull/%s', 'GH'),
+    'wiki': ('https://github.com/pvlib/pvlib-python/wiki/%s', 'wiki '),
+    'doi': ('http://dx.doi.org/%s', 'DOI: '),
+    'ghuser': ('https://github.com/%s', '@')
+}
 
 # -- Options for manual page output ---------------------------------------
 

docs/sphinx/source/contributing.rst

@@ -215,7 +215,7 @@ Remove any ``logging`` calls and ``print`` statements that you added
 during development. ``warning`` is ok.
 
 We typically use GitHub's
-"`squash and merge` <https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits>_"
+"`squash and merge <https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits>`_"
 feature to merge your pull request into pvlib. GitHub will condense the
 commit history of your branch into a single commit when merging into
 pvlib-python/master (the commit history on your branch remains
@@ -245,24 +245,35 @@ specific types may be used:
 
 Parameters that specify a specific type require that specific input type.
 
-A relatively easy way to test your documentation is to build it on
-`readthedocs.org <https://readthedocs.org>` by following their
-`Import Your Docs <http://docs.readthedocs.io/en/stable/getting_started.html#import-your-docs>`_
-instructions and enabling your branch on the readthedocs
-`versions admin page <http://docs.readthedocs.io/en/stable/features.html#versions>`_.
+Read the Docs will automatically build the documentation for each pull
+request. Please confirm the documentation renders correctly by following
+the ``continuous-documentation/read-the-docs`` link within the checks
+status box at the bottom of the pull request.
 
-Another option is to install the required dependencies in your virtual/conda
-environment. See
-`docs/environment.yml <https://github.com/pvlib/pvlib-python/blob/master/docs/environment.yml>`_
-for the latest dependences for building the complete documentation. Some
-doc files can be compiled with fewer dependencies, but this is beyond
-the scope of this guide.
+To build the docs locally, install the ``doc`` dependencies specified in the
+`setup.py <https://github.com/pvlib/pvlib-python/blob/master/setup.py>`_
+file. See :ref:`installation` instructions for more information.
 
 .. _testing:
 
 Testing
 ~~~~~~~
 
+Developers **must** include comprehensive tests for any additions or
+modifications to pvlib. New unit test code should be placed in the
+corresponding test module in the
+`pvlib/test <https://github.com/pvlib/pvlib-python/tree/master/pvlib/test>`_
+directory.
+
+A pull request will automatically run the tests for you on a variety of
+platforms (Linux, Mac, Windows) and python versions. However, it is
+typically more efficient to run and debug the tests in your own local
+environment.
+
+To run the tests locally, install the ``test`` dependencies specified in the
+`setup.py <https://github.com/pvlib/pvlib-python/blob/master/setup.py>`_
+file. See :ref:`installation` instructions for more information.
+
 pvlib's unit tests can easily be run by executing ``pytest`` on the
 pvlib directory:
 
@@ -287,12 +298,6 @@ location of a test failure. As described in :ref:`code-style`, pvlib
 code does not use ``print`` or ``logging`` calls, and this also applies
 to the test suite (with rare exceptions).
 
-New unit test code should be placed in the corresponding test module in
-the pvlib/test directory.
-
-Developers **must** include comprehensive tests for any additions or
-modifications to pvlib.
-
 pvlib-python contains 3 "layers" of code: functions, PVSystem/Location,
 and ModelChain. Contributors will need to add tests that correspond to
 the layers that they modify.