Merge pull request #255 from NREL/release/2.1.0-beta.2

Release/2.1.0 beta.2

.flake8

@@ -0,0 +1,11 @@
+# flake8 linter configurations
+# see https://flake8.pycqa.org/en/latest/user/options.html
+
+[flake8]
+max-line-length = 99
+max-doc-length = 99
+per-file-ignores =
+    # rdtools.x.y imported but unused
+    __init__.py:F401
+    # invalid escape sequence '\s'
+    versioneer.py:W605

.github/workflows/flake8.yaml

@@ -0,0 +1,34 @@
+name: flake8
+
+# since we're only checking PR diffs, only trigger on the pull_request event type.
+# note: the pull_request event happens on opened, reopened, and synchronize activities;
+# synchronize includes commits being pushed to the PR branch.
+# https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows#pull_request
+on: [pull_request]
+
+jobs:
+  lint:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0  # fetch all branches, needed so we can diff against the target branch
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install flake8
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8
+    - name: List changed files
+      run: |
+        git diff --compact-summary "origin/$GITHUB_BASE_REF"
+    - name: Run linter on changed files
+      run: |
+        git diff "origin/$GITHUB_BASE_REF" -- "*.py" | flake8 . --config=.flake8 --diff --count --statistics --show-source

.github/workflows/pytest.yaml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8, 3.9]
         env: [
           '-r requirements.txt .[test]',
           '-r requirements-min.txt .[test]',
@@ -19,6 +19,8 @@ jobs:
             env: '-r requirements-min.txt .[test]'
           - python-version: 3.8
             env: '-r requirements-min.txt .[test]'
+          - python-version: 3.9
+            env: '-r requirements-min.txt .[test]'
 
     steps:
     - uses: actions/checkout@v2
@@ -28,7 +30,7 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Install ${{ matrix.env }}
       run: |
-        python -m pip install --upgrade pip
+        python -m pip install --upgrade pip wheel
         pip install ${{ matrix.env }}
     - name: Test with pytest ${{ matrix.env }}
       run: |

docs/TrendAnalysis_example_pvdaq4.ipynb

@@ -394,7 +394,7 @@
   {
    "cell_type": "code",
    "execution_count": 17,
-   "metadata": {},
+   "metadata": {"tags": ["nbsphinx-thumbnail"]},
    "outputs": [
     {
      "data": {

docs/degradation_and_soiling_example_pvdaq_4.ipynb

@@ -329,8 +329,8 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
-   "metadata": {},
+   "execution_count": 8,
+   "metadata": {"tags": ["nbsphinx-thumbnail"]},
    "outputs": [
     {
      "data": {

docs/sphinx/source/changelog.rst

@@ -1,6 +1,7 @@
 RdTools Change Log
 ==================
 
+.. include:: changelog/v2.0.5.rst
 .. include:: changelog/v2.0.4.rst
 .. include:: changelog/v2.1.0-beta.0.rst
 .. include:: changelog/v2.0.3.rst

docs/sphinx/source/changelog/v2.0.5.rst

@@ -0,0 +1,28 @@
+**************************************************
+v2.0.5 (2020-12-30) and v2.1.0-beta.2 (2021-01-29)
+**************************************************
+
+Testing
+-------
+* Add a flake8 code style check to the continuous integration checks (:pull:`231`)
+* Moved several pytest fixtures from ``soiling_test.py`` and ``availability_test.py`` to ``conftest.py``
+  so that they are shared across test files (:pull:`231`)
+* Add Python 3.9 to CI testing (:pull:`249`)
+* Fix test suite error raised when using pandas 1.2.0 (:pull:`251`)
+
+Documentation
+-------------
+* Organized example notebooks into a sphinx gallery (:pull:`240`)
+
+Requirements
+------------
+* Add support for python 3.9 (:pull:`249`)
+* Update ``requirements.txt`` versions for numpy, scipy, pandas, h5py
+  and statsmodels to versions that have wheels available for python
+  3.6-3.9. Note that the minimum versions are unchanged. (:pull:`249`).
+
+Contributors
+------------
+* Kevin Anderson (:ghuser:`kanderso-nrel`)
+* Michael Deceglie (:ghuser:`mdeceglie`)
+* Chris Deline (:ghuser:`cdeline`)

docs/sphinx/source/conf.py

@@ -26,7 +26,7 @@
 author = 'kwhanalytics, Alliance for Sustainable Energy, LLC, and SunPower'
 
 # The full version, including alpha/beta/rc tags
-import rdtools
+import rdtools  # noqa: E402
 release = version = rdtools.__version__
 
 
@@ -42,6 +42,7 @@
     'sphinx.ext.autosummary',
     'nbsphinx',
     'nbsphinx_link',
+    'sphinx_gallery.load_style',
 ]
 
 autosummary_generate = True
@@ -84,6 +85,8 @@
 smartquotes = False
 
 master_doc = 'index'
+
+
 # A workaround for the responsive tables always having annoying scrollbars.
 def setup(app):
     app.add_stylesheet("no_scrollbars.css")
@@ -148,24 +151,20 @@ def make_github_url(pagename):
 
     # RTD automatically sets READTHEDOCS_VERSION to the version being built.
     rtd_version = os.environ.get('READTHEDOCS_VERSION', None)
+    if rtd_version is None:
+        # for other builds (PRs, local builds etc), it's unclear where to link
+        return None
+
     version_map = {
         'stable': 'master',
-        'latest': 'development',        
+        'latest': 'development',
     }
-    try:
-        branch = version_map[rtd_version]
-    except KeyError:
-        # for other builds (PRs, local builds etc), it's unclear where to link
-        return None
+    # for versions other than stable and latest, just use the version number.
+    # either a branch name or a git tag will work for the URL
+    branch = version_map.get(rtd_version, rtd_version)
 
     URL_BASE = "https://github.com/nrel/rdtools/blob/{}/".format(branch)
 
-    # map notebook pagenames to source files on github
-    notebook_map = {
-        'rd_example': 'degradation_and_soiling_example_pvdaq_4.ipynb',
-        'system_availability_example': 'system_availability_example.ipynb',
-    }
-
     # is it an API autogen page?
     if pagename.startswith("generated/"):
         # pagename looks like "generated/rdtools.degradation.degradation_ols"
@@ -179,21 +178,22 @@ def make_github_url(pagename):
             target_url += '#L{}-L{}'.format(start, end)
 
     # is it an example notebook?
-    elif pagename in notebook_map:
-        target_url = URL_BASE + "docs/" + notebook_map[pagename]
+    elif pagename.startswith('examples/'):
+        notebook_name = pagename.split("/")[-1]
+        target_url = URL_BASE + "docs/" + notebook_name + ".ipynb"
 
     # is the the changelog page?
     elif pagename == "changelog":
         target_url = URL_BASE + "docs/sphinx/source/changelog"
-        
+
     # Just a normal source RST page
     else:
         target_url = URL_BASE + "docs/sphinx/source/" + pagename + ".rst"
 
-    display_text = "View on github/" + branch
+    display_text = "View on github@" + branch
     link_info = {
         'url': target_url,
-        'text': display_text        
+        'text': display_text
     }
     return link_info
 
@@ -202,4 +202,4 @@ def make_github_url(pagename):
 # _templates/breadcrumbs.html
 html_context = {
     'make_github_url': make_github_url,
-}
+}

docs/sphinx/source/developer_notes.rst

@@ -79,21 +79,21 @@ Optional dependencies can be installed with the special
 ::
 
     pip install rdtools[test]  # test suite dependencies
-    pip install rdtools[doc]   # documentation dependecies
+    pip install rdtools[doc]   # documentation dependencies
 
 Or, if your local repository has an updated dependencies list:
 
 ::
 
     pip install .[test]  # test suite dependencies
-    pip install .[doc]   # documentation dependecies
+    pip install .[doc]   # documentation dependencies
 
 
 Running the test suite
 ----------------------
 
 RdTools uses `pytest <https://docs.pytest.org/en/latest/>`_ to run its test
-suite.  If you haven't already, install the testing depencencies
+suite.  If you haven't already, install the testing dependencies
 (:ref:`installing-optional-dependencies`).
 
 To run the entire test suite, navigate to the git repo folder and run
@@ -131,11 +131,31 @@ function isn't tested or a branch inside a function isn't tested.  To get
 specific details, you can run ``coverage html`` to generate a detailed HTML
 report at ``htmlcov/index.html`` to view in a browser.  
 
+
+Checking for code style
+-----------------------
+
+RdTools uses `flake8 <https://flake8.pycqa.org/en/latest/>`_ to validate
+code style. To run this check locally you'll need to have flake8 installed
+(see :ref:`installing-optional-dependencies`). Then navigate to the git repo
+folder and run
+
+::
+
+    flake8
+
+Or, for a more detailed report:
+
+::
+
+    flake8 --count --statistics --show-source
+
+
 Building documentation locally
 ------------------------------
 
 RdTools uses `Sphinx <https://www.sphinx-doc.org/>`_ to build its documentation.
-If you haven't already, install the documentation depencencies
+If you haven't already, install the documentation dependencies
 (:ref:`installing-optional-dependencies`).
 
 Once the required packages are installed, change your console's working
@@ -193,7 +213,7 @@ Community participation is welcome!  New contributions should be based on the
 
 RdTools follows the `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ style guide.
 We recommend setting up your text editor to automatically highlight style
-violations because it's easy to miss some isses (trailing whitespace, etc) otherwise.
+violations because it's easy to miss some issues (trailing whitespace, etc) otherwise.
 
 Additionally, our documentation is built in part from docstrings in the source
 code.  These docstrings must be in `NumpyDoc format <https://numpydoc.readthedocs.io/en/latest/format.html>`_

docs/sphinx/source/examples.rst

@@ -0,0 +1,27 @@
+.. _examples:
+
+Examples
+========
+
+This page shows example usage of the RdTools analysis functions.
+
+
+.. Note that the entries in the list below are nblink filenames, not notebook filenames!
+
+.. There is a limitation in sphinx that I don't understand, but it means that
+   you cannot directly access files outside the source directory unless you use
+   something like nbsphinx_link, which is what we do here.
+   To add a notebook to the gallery, create a .nblink file and add it to the list below.
+   Note: the make_github_url() function in conf.py assumes that the name of the .nblink file
+   is the same as the notebook it points to!
+
+.. To select a thumbnail image, you need to edit the metadata of the cell with the
+   desired image to include a special tags value:
+        "metadata": {"tags": ["nbsphinx-thumbnail"]},
+
+
+.. nbgallery::
+
+    examples/degradation_and_soiling_example_pvdaq_4
+    examples/TrendAnalysis_example_pvdaq4
+    examples/system_availability_example

docs/sphinx/source/examples/TrendAnalysis_example_pvdaq4.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../TrendAnalysis_example_pvdaq4.ipynb"
+}

docs/sphinx/source/examples/degradation_and_soiling_example_pvdaq_4.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../degradation_and_soiling_example_pvdaq_4.ipynb"
+}

docs/sphinx/source/examples/system_availability_example.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../../system_availability_example.ipynb"
+}

docs/sphinx/source/index.rst

@@ -22,8 +22,7 @@ analyze systems for system- and subsystem-level availability. RdTools can handle
 both high frequency (hourly or better) or low frequency (daily, weekly,
 etc.) datasets. Best results are obtained with higher frequency data.
 
-Full examples are worked out in the example notebooks in the
-`example notebook`_.
+Full examples are worked out in the notebooks shown in :ref:`examples`.
 
 To report issues, contribute code, or suggest improvements to this
 documentation, visit the RdTools development repository on `github`_.
@@ -43,7 +42,7 @@ supported. A typical analysis of soiling and degradation contains the following:
    soiling loss
 
 Steps 1 and 2 may be accomplished with the clearsky workflow (see the
-`example notebook`_) which can help eliminate problems from irradiance sensor
+:ref:`examples`) which can help eliminate problems from irradiance sensor
 drift.
 
 .. image:: _images/RdTools_workflows.png
@@ -58,7 +57,7 @@ The YOY calculation yields in a distribution of degradation rates, the
 central tendency of which is the most representative of the true
 degradation. The width of the distribution provides information about
 the uncertainty in the estimate via a bootstrap calculation. The
-`example notebook`_ uses the output of
+:ref:`examples` use the output of
 :py:func:`.degradation.degradation_year_on_year` to visualize the calculation.
 
 .. image:: _images/Clearsky_result_updated.png
@@ -151,7 +150,7 @@ RdTools currently is tested on Python 3.6+.
 Usage and examples
 ------------------
 
-Full workflow examples are found in the notebooks in `example notebook`_.
+Full workflow examples are found in the notebooks in :ref:`examples`.
 The examples are designed to work with python 3.7. For a consistent
 experience, we recommend installing the packages and versions documented
 in ``docs/notebook_requirements.txt``. This can be achieved in your
@@ -291,9 +290,7 @@ Documentation Contents
 .. toctree::
    :maxdepth: 2
 
-   Degradation and Soiling <rd_example>
-   TrendAnalysis <TrendAnalysis_example>
-   Inverter Downtime <system_availability_example>
+   Examples <examples>
    API Reference <api>
    Change Log <changelog>
    Developer Notes <developer_notes>
@@ -307,7 +304,6 @@ Indices and tables
 
 
 .. links and references
-.. _TrendAnalysis example: TrendAnalysis_example.nblink 
-.. _example notebook: rd_example.nblink
+
 .. _release: https://github.com/NREL/rdtools/releases
 .. _github: https://github.com/NREL/rdtools