Merge pull request #37 from kbonney/docstrings

Docstrings

.github/workflows/builddocs.yml

@@ -0,0 +1,45 @@
+# This is a basic workflow to help you get started with Actions
+
+name: docs build experiment
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    branches: [ master, docstrings ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Install pandoc
+        run: sudo apt-get update -y && sudo apt-get install -y pandoc
+      - uses: actions/setup-python@v2
+        with: 
+          python-version: '3.8' 
+      - name: Setup Python 3.8
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+          pip install --upgrade coverage pytest
+      - name: Install package
+        run: |
+          python -m pip install -e .
+      - name: Build documentation
+        run: sphinx-build -b html docs/ docs/_build/html
+      - uses: actions/upload-artifact@v3
+        with:
+          name: html-docs
+          path: docs/_build/html

docs/_static/css/my_style.css

@@ -0,0 +1,5 @@
+@import url("theme.css");
+
+.wy-nav-content {
+    max-width: 1000px !important;
+}

docs/conf.py

@@ -13,32 +13,14 @@
 import os
 import sys
 
-import mock
-MODULES = ['numpy', 'nltk', 'sklearn.pipeline', 'sklearn.model_selection',
-           'scipy.sparse', 'pandas', 'scipy', 'sklearn.base',
-           'gensim.models.doc2vec', 'nltk.tokenize', 'datefinder',
-           'text_remove_nondate_nums', 'text_remove_numbers_stopwords',
-           'get_dates', 'gensim.models', 'sklearn.svm', 'sklearn.tree',
-           'sklearn.neural_network', 'sklearn.linear_model',
-           'sklearn.ensemble', "sklearn.cluster", "networkx", "matplotlib",
-           "matplotlib.pyplot", "gensim.models.doc2vec",
-           "sklearn.feature_extraction.text", "nltk.tokenize",
-           "plotly.graph_objects", "scipy.signal", 'matplotlib.colors',
-           'seaborn', 'matplotlib.ticker', 'scipy.signal.find_peaks',
-           'pvlib', 'pvanalytics', 'timezonefinder', 'sklearn', "pyDOE",
-           "sklearn.metrics", "scipy.interpolate", "keras", "keras.layers",
-           "sklearn.utils", "sklearn.preprocessing", "keras.models",
-           "keras.utils"]
-
-for module in MODULES:
-    sys.modules[module] = mock.Mock()
 
 sys.path.insert(0, os.path.abspath("../pvops"))
 sys.path.insert(0, os.path.abspath("../pvops/text2time"))
 sys.path.insert(0, os.path.abspath("../pvops/text"))
 sys.path.insert(0, os.path.abspath("../pvops/timeseries"))
+sys.path.insert(0, os.path.abspath("../pvops/timeseries/models"))
 sys.path.insert(0, os.path.abspath("../pvops/iv"))
-
+sys.path.insert(0, os.path.abspath("../pvops/iv/models"))
 
 # -- Project information -----------------------------------------------------
 
@@ -55,10 +37,37 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc",
-              "nbsphinx",
-              "nbsphinx_link",
-              "sphinx_copybutton"]
+extensions = [
+    "sphinx.ext.autodoc",
+    # pull in documentation from docstrings in a semi-automatic way.
+    "nbsphinx",
+    # nbsphinx is a Sphinx extension that provides a source parser
+    # for *.ipynb files
+    "nbsphinx_link",
+    # A sphinx extension for including notebook files from outside
+    # the sphinx source root.
+    "sphinx_copybutton",
+    # adds copy button to code blocks
+    "sphinx.ext.coverage",
+    # `make coverage` summarizes what has docstrings
+    'sphinx.ext.doctest',
+    # allows for testing of code snippets
+    'sphinx.ext.viewcode',
+    # add links to highlighted source code
+    'sphinx.ext.napoleon'
+    # add parsing for google/numpy style docs
+]
+
+
+coverage_show_missing_items = True
+napoleon_numpy_docstring = True  # use numpy style
+napoleon_google_docstring = False  # not google style
+napoleon_use_rtype = False  # option for return section formatting
+numpydoc_show_class_members = True
+numpydoc_show_inherited_class_members = False
+numpydoc_class_members_toctree = False
+napoleon_use_ivar = True  # option for attribute section formatting
+napoleon_use_param = False  # option for parameter section formatting
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -80,3 +89,4 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_style = 'css/my_style.css'

docs/requirements.txt

@@ -1,4 +1,5 @@
 ipykernel
 nbsphinx
 nbsphinx-link
-sphinx-copybutton
+sphinx-copybutton
+sphinx_rtd_theme

docs/timeseries.rst

@@ -17,3 +17,18 @@ timeseries.models.linear module
    :undoc-members:
    :show-inheritance:
 
+timeseries.models.AIT module
+-------------------------------
+
+.. automodule:: timeseries.models.AIT
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+timeseries.models.iec module
+-------------------------------
+
+.. automodule:: timeseries.models.iec
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/whatsnew/alpha.rst

@@ -1,5 +1,3 @@
-.. _whatsnew_alpha:
-
 First push
 -----------------------
 

docs/whatsnew/beta.rst

@@ -1,5 +1,3 @@
-.. _whatsnew_beta:
-
 beta 
 -----------------------
 

pvops/iv/extractor.py

@@ -4,37 +4,38 @@
 
 import numpy as np
 import matplotlib.pyplot as plt
-from physics_utils import calculate_IVparams, smooth_curve
 import scipy
 import sklearn
-from simulator import Simulator
+from pvops.iv.simulator import Simulator
 import time
-from physics_utils import iv_cutoff, T_to_tcell
+from pvops.iv.physics_utils import iv_cutoff, T_to_tcell, \
+    calculate_IVparams, smooth_curve
 
 
 class BruteForceExtractor():
     '''Process measured IV curves
-        Requires a set of curves to create Isc vs Irr and Voc vs Temp vs Isc(Irr)
+    Requires a set of curves to create Isc vs Irr and Voc vs Temp vs Isc(Irr)
+
+    Parameters
+    ----------
+    input_df : DataFrame
+        Contains IV curves with a datetime index
+    current_col : string
+        Indicates column where current values in IV curve are located;
+        each cell is an array of current values in a single IV curve
+    voltage_col : string
+        Indicates column where voltage values in IV curve are located;
+        each cell is an array of voltage values in a single IV curve
+    irradiance_col : string
+        Indicates column where irradiance value (W/m2)
+    temperature_col : string
+        Indicates column where temperature value (C)
+    T_type : string
+        Describe input temperature, either 'ambient' or 'module' or 'cell'
     '''
 
     def __init__(self, input_df, current_col, voltage_col, irradiance_col, temperature_col, T_type, windspeed_col=None,
                  Simulator_mod_specs=None, Simulator_pristine_condition=None):
-        '''
-        Parameters
-        ----------
-        input_df, df
-            Contains IV curves with a datetime index
-        current_col, str
-            Indicates column where current values in IV curve are located; each cell is an array of current values in a single IV curve
-        voltage_col, str
-            Indicates column where voltage values in IV curve are located; each cell is an array of voltage values in a single IV curve
-        irradiance_col, str
-            Indicates column where irradiance value (W/m2)
-        temperature_col, str
-            Indicates column where temperature value (C)
-        T_type: string,
-            Describe input temperature, either 'ambient' or 'module' or 'cell'
-        '''
 
         self.Simulator_mod_specs = Simulator_mod_specs
         self.Simulator_pristine_condition = Simulator_pristine_condition
@@ -76,6 +77,7 @@ def __init__(self, input_df, current_col, voltage_col, irradiance_col, temperatu
         self.params = {}
 
     def create_string_object(self, iph, io, rs, rsh, nnsvth):
+        # TODO write docstring
         kwargs = {}
         if self.Simulator_mod_specs is not None:
             kwargs.update({'mod_specs': self.Simulator_mod_specs})
@@ -127,7 +129,7 @@ def create_string_object(self, iph, io, rs, rsh, nnsvth):
         return sim
 
     def f_multiple_samples(self, params):
-
+        # TODO write docstring
         iph, io, rs, rsh, nnsvth = params
 
         if self.user_func is None:
@@ -235,16 +237,18 @@ def f_multiple_samples(self, params):
         return msse_tot
 
     def fit_params(self, cell_parameters, n_mods, bounds_func, user_func=None, verbose=0):
-        """Fit diode parameters from a set of IV curves.
+        """
+        Fit diode parameters from a set of IV curves.
 
         Parameters
-
         ----------
         cell_parameters : dict
-            Cell-level parameters, usually extracted from the CEC database, which will be used as the
+            Cell-level parameters, usually extracted from the CEC
+            database, which will be used as the
             initial guesses in the optimization process.
         n_mods : int
-            if int, defines the number of modules in a string(1=simulate a single module)
+            if int, defines the number of modules in a
+            string(1=simulate a single module)
         bounds_func : function
             Function to establish the bounded search space
             See below for an example:
@@ -259,8 +263,10 @@ def bounds_func(iph,io,rs,rsh,nnsvth,perc_adjust=0.5):
                             (nnsvth - 10*nnsvth*perc_adjust, nnsvth + 10*nnsvth*perc_adjust))
 
         user_func : function
-            Optional, a function similar to `self.create_string_object` which has the following inputs:
-            `self, iph, io, rs, rsh, nnsvth`. This can be used to extract unique failure parameterization.
+            Optional, a function similar to `self.create_string_object`
+            which has the following inputs:
+            `self, iph, io, rs, rsh, nnsvth`. This can be used to
+            extract unique failure parameterization.
         verbose : int
             if verbose >= 1, print information about fitting
             if verbose >= 2, plot information about each iteration