Docstring standardization and pep8 formatting

.gitignore

@@ -19,6 +19,9 @@
 docs/.ipynb_checkpoints/degradation_example-checkpoint.ipynb
 *.ipynb_checkpoints*
 
+# sphinx docs build
+docs/sphinx/source/generated
+
 # ignore setup and egg-info
 .eggs/
 build/

.readthedocs.yml

@@ -0,0 +1,6 @@
+python:
+    version: 3.6
+    install:
+      - requirements: docs/sphinx/sphinx_requirements.txt
+    use_system_site_packages: true
+    pip_install: true

README.md

@@ -1,15 +1,18 @@
 # About RdTools
 
-Master branch: [![Build Status](https://travis-ci.org/NREL/rdtools.svg?branch=master)](https://travis-ci.org/NREL/rdtools)  
-Development branch: [![Build Status](https://travis-ci.org/NREL/rdtools.svg?branch=development)](https://travis-ci.org/NREL/rdtools)
+Master branch: 
+[![Build Status](https://travis-ci.org/NREL/rdtools.svg?branch=master)](https://travis-ci.org/NREL/rdtools)  
+
+Development branch: 
+[![Build Status](https://travis-ci.org/NREL/rdtools.svg?branch=development)](https://travis-ci.org/NREL/rdtools)
 
 RdTools is a set of Python tools for analysis of photovoltaic data.
 In particular, PV production data is evaluated over several years
 to obtain rates of performance degradation and soiling loss. 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 [rdtools/docs](./docs/degradation_example.ipynb).
+Full examples are worked out in the example notebooks in the [documentation](https://rdtools.readthedocs.io/en/latest/example.html).
 
 ## Workflow
 RdTools supports a number of workflows, but a typical analysis follows the following: 
@@ -20,21 +23,21 @@ RdTools supports a number of workflows, but a typical analysis follows the follo
 3. Aggregate data
 4. Analyze aggregated data to estimate the degradation rate and/or soiling loss  
 
-Steps 1 and 2 may be accomplished with the clearsky workflow ([see example](./docs/degradation_example.ipynb))
+Steps 1 and 2 may be accomplished with the clearsky workflow ([see example](https://rdtools.readthedocs.io/en/latest/example.html))
 which can help elliminate problems from irradiance sensor drift.  
 
-<img src="./screenshots/RdTools_workflows.png" width="400" height="247" alt="RdTools Workflow"/>
+<img src="./_static/RdTools_workflows.png" width="400" height="247" alt="RdTools Workflow"/>
 
 ## Degradation Results
 
 The preferred method for degradation rate estimation is the year-on-year (YOY) approach,
 available in `degradation.degradation_year_on_year`. 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](./docs/degradation_example.ipynb) uses the output of `degradation.degradation_year_on_year()`
+estimate via a bootstrap calculation. The [example notebook](https://rdtools.readthedocs.io/en/latest/example.html) uses the output of `degradation.degradation_year_on_year()`
 to visualize the calculation.
 
-<img src="./screenshots/Clearsky_result_updated.png" width="600" height="456" alt="RdTools Result"/>
+<img src="./_static/Clearsky_result_updated.png" width="600" height="456" alt="RdTools Result"/>
 
 
 Two workflows are available for system performance ratio calculation, and illustrated in an example notebook. 
@@ -48,7 +51,7 @@ of instrument errors or irradiance sensor drift, such as in the above analysis.
 ## Soiling Results
 Soiling can be estimated with the stochastic rate and recovery (SRR) method (Deceglie 2018). This method works well when soiling patterns follow a "sawtooth" pattern, a linear decline followed by a sharp recovery associated with natural or mannual cleaning. `rdtools.soiling_srr()` performs the calculation and returns the P50 insolation-weighted soiling ratio, confidence interval, and additional information (`soiling_info`) which includes a summary of the soiling intervals identified, `soiling_info['soiling_interval_summary']`. This summary table can, for example, be used to plot a histogram of the identified soiling rates for the dataset.  
 
-<img src="./screenshots/soiling_histogram.png" width="320" height="216" alt="RdTools Result"/>
+<img src="./_static/soiling_histogram.png" width="320" height="216" alt="RdTools Result"/>
 
 ## Install RdTools using pip
 
@@ -68,7 +71,7 @@ RdTools currently runs in both Python 2.7 and 3.6.
 ## Usage and examples
 
 
-Full workflow examples are found in the notebooks in [rdtools/docs](./docs/degradation_example.ipynb). The examples are designed to work with python 3.6. For a consistent experience, we recommend installing the packages and versions documented in `docs/notebook_requirements.txt`. This can be achieved in your environment by first installing RdTools as described above, then running `pip install -r docs/notebook_requirements.txt` from the base directory.
+Full workflow examples are found in the notebooks in [rdtools/docs](https://rdtools.readthedocs.io/en/latest/example.html). The examples are designed to work with python 3.6. For a consistent experience, we recommend installing the packages and versions documented in `docs/notebook_requirements.txt`. This can be achieved in your environment by first installing RdTools as described above, then running `pip install -r docs/notebook_requirements.txt` from the base directory.
 
 The following functions are used for degradation analysis:
 
@@ -124,11 +127,26 @@ soiling.soiling_srr(aggregated, aggregated_insolation)
 
 ## Citing RdTools
 
+<!-- Markdown to RST conversion messes up on the following bulleted lists  -->
+<!-- because some of them start with intials (eg - D. Jordan...) and RST -->
+<!-- ends up parsing the initials as nested bullet points because it allows -->
+<!-- alpha characters as list item delimiters.  I can't find a way to -->
+<!-- disable that behavior, nor can I find a way to get the m2r converter -->
+<!-- to solve the issue.  Additionally formatting these lines as pretext -->
+<!-- or similar makes it really ugly.  The fix is to include text on the -->
+<!-- following line after each bullet, aligned with the initial that causes -->
+<!-- the problem -- that alerts sphinx that the initial is text and not a -->
+<!-- delimiter.  But since we don't actually want any visible text there, -->
+<!-- I've put an invisible unicode space character in that slot.  Ugly hack,-->
+<!-- but it makes things display correctly in both MD and RST, so... -->
+<!-- The character is '\u200c' -->
+
 The underlying workflow of RdTools has been published in several places.  If you use RdTools in a published work, please cite the following as appropriate:
 
-  - D. Jordan, C. Deline, S. Kurtz, G. Kimball, M. Anderson, "Robust PV Degradation Methodology and Application",
-  IEEE Journal of Photovoltaics, 8(2) pp. 525-531, 2018  
+  - D. Jordan, C. Deline, S. Kurtz, G. Kimball, M. Anderson, "Robust PV Degradation Methodology and Application", IEEE Journal of Photovoltaics, 8(2) pp. 525-531, 2018  
+    ‌‌ 
   - M. G. Deceglie, L. Micheli and M. Muller, "Quantifying Soiling Loss Directly From PV Yield," in IEEE Journal of Photovoltaics, 8(2), pp. 547-551, 2018  
+    ‌‌ 
   - RdTools, version x.x.x, https://github.com/NREL/rdtools, [DOI:10.5281/zenodo.1210316](https://doi.org/10.5281/zenodo.1210316)  
   *(be sure to include the version number used in your analysis)*
 
@@ -142,10 +160,16 @@ https://neo.sci.gsfc.nasa.gov/view.php?datasetId=MOD_LSTN_CLIM_M
 
 Other useful references which may also be consulted for degradation rate methodology include:
 
+<!-- See above for explanation of unicode space characters in list -->
+
   - D. C. Jordan, M. G. Deceglie, S. R. Kurtz, “PV degradation methodology comparison — A basis for a standard”, in 43rd IEEE Photovoltaic Specialists Conference, Portland, OR, USA, 2016, DOI: 10.1109/PVSC.2016.7749593.
+    ‌‌ 
   - Jordan DC, Kurtz SR, VanSant KT, Newmiller J, Compendium of Photovoltaic Degradation Rates, Progress in Photovoltaics: Research and Application, 2016, 24(7), 978 - 989.
+    ‌‌ 
   - D. Jordan, S. Kurtz, PV Degradation Rates – an Analytical Review, Progress in Photovoltaics: Research and Application, 2013, 21(1), 12 - 29.
+    ‌‌ 
   - E. Hasselbrink, M. Anderson, Z. Defreitas, M. Mikofski, Y.-C.Shen, S. Caldwell, A. Terao, D. Kavulak, Z. Campeau, D. DeGraaff, “Validation of the PVLife model using 3 million module-years of live site data”, 39th IEEE Photovoltaic Specialists Conference, Tampa, FL, USA, 2013, p. 7 – 13, DOI: 10.1109/PVSC.2013.6744087.
+    ‌‌ 
 
 ## Further Instructions and Updates
 

docs/degradation_and_soiling_example.ipynb

@@ -65,7 +65,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 0: Import and preliminary calculations\n",
+    "## 0: Import and preliminary calculations\n",
     "\n",
     "\n",
     "This section prepares the data necesary for an `rdtools` calculation. The first step of the `rdtools` workflow is normaliztion, which requires a time series of energy yield, a time series of cell temperature, and a time series of irradiance, along with some metadata (see Step 1: Normalize)\n",
@@ -169,7 +169,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 1: Normalize\n",
+    "## 1: Normalize\n",
     "\n",
     "Data normalization is achieved with `rdtools.normalize_with_pvwatts()`. We provide a time sereis of energy, along with keywords used to run a pvwatts model of the system. More information available in the docstring."
    ]
@@ -218,7 +218,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 2: Filter\n",
+    "## 2: Filter\n",
     "\n",
     "Data filtering is used to exclude data points that represent invalid data, create bias in the analysis, or introduce significant noise.\n",
     "\n",
@@ -265,7 +265,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 3: Aggregate\n",
+    "## 3: Aggregate\n",
     "\n",
     "Data is aggregated with an irradiance weighted average. This can be useful, for example with daily aggregation, to reduce the impact of high-error data points in the morning and evening."
    ]
@@ -300,7 +300,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 4: Degradation calculation\n",
+    "## 4: Degradation calculation\n",
     "\n",
     "Data is then analyzed to estimate the degradation rate representing the PV system behavior. The results are visualized and statistics are reported, including the 68.2% confidence interval, and the P95 exceedence value."
    ]
@@ -385,7 +385,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 5: Soiling calculations  \n",
+    "## 5: Soiling calculations  \n",
     "\n",
     "This section illustrates how the aggreagated data can be used to estimate soiling losses using the stochastic rate and recovery (SRR) method.<sup>1</sup>\n",
     "\n",
@@ -658,7 +658,7 @@
     "heading_collapsed": true
    },
    "source": [
-    "# Clear sky workflow\n",
+    "## Clear sky workflow\n",
     "The clear sky workflow is useful in that it avoids problems due to drift or recalibration of ground-based sensors. We use `pvlib` to model the clear sky irradiance. This is renormalized to align it with ground-based measurements. Finally we use `rdtools.get_clearsky_tamb()` to model the ambient temperature on clear sky days. This modeled ambient temperature is used to model cell temperature with `pvlib`. If high quality amabient temperature data is available, that can be used instead of the modeled ambient; we proceed with the modeled ambient temperature here for illustrative purposes.\n",
     "\n",
     "In this example, note that we have omitted wind data in the cell temperature calculations for illustrative purposes. Wind data can also be included when the data source is trusted for improved results\n",
@@ -670,7 +670,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Clear Sky 0: Preliminary Calculations"
+    "## Clear Sky 0: Preliminary Calculations"
    ]
   },
   {
@@ -703,7 +703,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Clear Sky 1: Normalize\n",
+    "## Clear Sky 1: Normalize\n",
     "Normalize as in step 1 above, but this time using clearsky modeled irradiance and cell temperature"
    ]
   },
@@ -732,7 +732,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Clear Sky 2: Filter\n",
+    "## Clear Sky 2: Filter\n",
     "Filter as in step 2 above, but with the addition of a clear sky index (csi) filter so we consider only points well modeled by the clear sky irradiance model."
    ]
   },
@@ -760,7 +760,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Clear Sky 3: Aggregate\n",
+    "## Clear Sky 3: Aggregate\n",
     "Aggregate the clear sky version of of the filtered data "
    ]
   },
@@ -779,7 +779,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Clear Sky 4: Degradation Calculation\n",
+    "## Clear Sky 4: Degradation Calculation\n",
     "Estimate the degradation rate and compare to the results obtained with sensors. In this case, we see that irradiance sensor drift may have biased the sensor-based results, a problem that is corrected by the clear sky approach."
    ]
   },
@@ -888,9 +888,9 @@
  "metadata": {
   "anaconda-cloud": {},
   "kernelspec": {
-   "display_name": "Python [default]",
+   "display_name": "Python 3",
    "language": "python",
-   "name": "python2"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -902,7 +902,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.8"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,

docs/sphinx/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/sphinx/build.bat

@@ -0,0 +1,18 @@
+
+:: helper script for building locally, written by KSA
+:: not sure if this is redundant with the makefile.
+:: the makefile might only build the html, it might not run sphinx-apidoc
+
+:: pip install sphinx_rtd_theme
+:: pip install m2r
+:: pip install nbsphinx
+:: pip install nbsphinx-link
+
+rmdir /s /q .\docs\sphinx\build
+mkdir .\docs\sphinx\build
+
+:: sphinx-apidoc -f -o docs/sphinx/source ./rdtools /separate
+
+sphinx-build -b html docs/sphinx/source docs/sphinx/build
+
+xcopy /I .\screenshots .\docs\sphinx\build\screenshots

docs/sphinx/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/sphinx/source/_static/no_scrollbars.css

@@ -0,0 +1,11 @@
+/* override table width restrictions */
+/* see https://github.com/snide/sphinx_rtd_theme/issues/117 */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    /* !important prevents the common CSS stylesheets from
+       overriding this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+}
+
+.wy-table-responsive {
+    overflow: visible !important;
+}