Updated documentation and simple example config (sandialabs#86)

* bump action versions

* Minor updates to documentation, including the use of sphinxcontrib.bibtex

* update simple example config to support np

* removed version number from figure

* updated release notes

* Added documentation requirements

Author: kaklise

documentation/applications.rst

@@ -13,12 +13,12 @@ For PV systems, the translation dictionary can be used to group data
 according to the system architecture, which can include multiple strings and modules.
 The time filter can be defined based on sun position and system location.
 The data objects used in Pecos are compatible with `PVLIB <http://pvlib-python.readthedocs.io/>`_, which can be used to model PV 
-systems [SHFH16]_.
+systems :cite:p:`pvlib`.
 Pecos also includes functions to compute PV specific metrics (i.e. insolation, 
 performance ratio, clearness index) in the :class:`~pecos.pv` module.
 The International Electrotechnical Commission (IEC) has developed guidance to measure 
 and analyze energy production from PV systems. 
-Klise et al. [KlSC17]_ describe an application of IEC 61724-3, using 
+Klise et al. :cite:p:`klise17` describe an application of IEC 61724-3, using 
 Pecos and PVLIB.
 Pecos includes a PV system example in the `examples/pv <https://github.com/sandialabs/pecos/tree/main/examples/pv>`_ directory.  
 
@@ -34,4 +34,9 @@ Fossil energy systems
 In partnership with National Energy Technology Laboratory (NETL), Pecos was extended to demonstrate real-time monitoring of coal-fired power plants in support of the Department of Energy's `Institute for the Design of Advanced Energy Systems (IDAES) <https://idaes.org/>`_.
 As part of this demonstration, streaming algorithms were added to Pecos to facilitate near real-time analysis using continuous data streams. 
 
+Water treatment systems
+-----------------------
+
+As part of a Water Research Foundation Project, Pecson et al. :cite:p:`wrf24` used Pecos to develop a real-time
+event detection system for direct potable reuse at the San Diego North City Pure Water Demonstration Facility.
 

documentation/conf.py

@@ -40,10 +40,32 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
-]
-
-napoleon_use_rtype = False
-viewcode_import = True
+    'sphinx_design',
+    'sphinxcontrib.bibtex'
+]    
+
+add_function_parentheses = True
+add_module_names = False
+python_display_short_literal_types = True
+
+toc_object_entries = True
+toc_object_entries_show_parents = 'hide'
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = True
+napoleon_preprocess_types = False
+napoleon_use_ivar = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_use_keyword = False
+
+# viewcode_import = False
 numpydoc_show_class_members = True
 numpydoc_class_members_toctree = False
 autodoc_member_order = 'bysource'
@@ -70,6 +92,10 @@
 copyright = u'2016, National Technology & Engineering Solutions of Sandia, LLC (NTESS)'
 author = u'Sandia National Laboratories'
 
+bibtex_bibfiles = ['references.bib']
+bibtex_default_style = 'plain'
+bibtex_reference_style = 'label'
+
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
@@ -84,7 +110,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -138,17 +164,19 @@ def setup(app):
     import sphinx_rtd_theme
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]     
-    html_style = 'pecos.css'                      
+    html_style = 'pecos.css'
 else:
+    def setup(app):
+        app.add_css_file( "pecos.css")
     html_theme = 'default'
 #    html_context = {
 #        'css_files': ['_static/pecos.css'],
-#    }             
+#    }  
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -162,7 +190,7 @@ def setup(app):
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = 'figures/logo.jpg'                                                   
+#html_logo = 'figures/logo.png'                                                   
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

documentation/developers.rst

@@ -4,9 +4,10 @@ Developers
 The following services are used for software quality assurance:
 
 * The software repository is hosted on GitHub at https://github.com/sandialabs/pecos.  
+* Bug reports and feature requests can be submitted to https://github.com/sandialabs/pecos/issues.
 * Automated testing is run using GitHub Actions at https://github.com/sandialabs/pecos/actions.
 * Test coverage statistics are collected using Coveralls at https://coveralls.io/github/sandialabs/pecos.
-* The current release is hosted on PyPI at https://pypi.python.org/pypi/pecos.
+* The current release is hosted on PyPI at https://pypi.python.org/pypi/pecos and conda-forge at https://anaconda.org/conda-forge/pecos.
 
 Tests can be run locally using pytest::
 

documentation/environment.yml

@@ -1,6 +1,6 @@
 name: pecos
 dependencies:
-    - python=3.9
+    - python=3.11
     - numpy
     - pandas
     - pytz

documentation/figures/monitoring_report.png

@@ -32,8 +32,8 @@ Citing Pecos
 --------------
 To cite Pecos, use one of the following references:
 
-* K.A. Klise and J.S. Stein (2016), Performance Monitoring using Pecos, Technical Report SAND2016-3583, Sandia National Laboratories, Albuquerque, NM.
-* K.A. Klise and J.S. Stein (2016), Automated Performance Monitoring for PV Systems using Pecos, 43rd IEEE Photovoltaic Specialists Conference (PVSC), Portland, OR, June 5-10. `pdf <http://www.pvsc-proceedings.org./download.php?year=2016&file=907>`_
+* K.A. Klise and J.S. Stein (2016), Performance Monitoring using Pecos, Technical Report SAND2016-3583, Sandia National Laboratories, Albuquerque, NM. :cite:p:`klise16a`
+* K.A. Klise and J.S. Stein (2016), Automated Performance Monitoring for PV Systems using Pecos, 43rd IEEE Photovoltaic Specialists Conference (PVSC), Portland, OR, June 5-10. :cite:p:`klise16b` `pdf <http://www.pvsc-proceedings.org./download.php?year=2016&file=907>`_
 
 Contents
 ------------

documentation/index.rst

@@ -1,7 +1,7 @@
 Installation
 ======================================
 
-Pecos requires Python (tested on 3.8, 3.9, and 3.10) along with several Python 
+Pecos requires Python (tested on 3.9, 3.10, 3.11, and 3.12) along with several Python 
 package dependencies.  Information on installing and using Python can be found at 
 https://www.python.org/.  Python distributions, such as Anaconda,
 are recommended to manage the Python interface.  
@@ -51,27 +51,27 @@ Dependencies
 
 Required Python package dependencies include:
 
-* Pandas [Mcki13]_: used to analyze and store time series data, 
+* Pandas :cite:p:`pandas`: used to analyze and store time series data, 
   http://pandas.pydata.org/
-* Numpy [VaCV11]_: used to support large, multi-dimensional arrays and matrices, 
+* Numpy :cite:p:`numpy`: used to support large, multi-dimensional arrays and matrices, 
   http://www.numpy.org/
-* Jinja [Rona08]_: used to generate HTML templates, 
-  http://jinja.pocoo.org/
-* Matplotlib [Hunt07]_: used to produce figures, 
+* Jinja :cite:p:`jinja`: used to generate HTML templates, 
+  https://jinja.palletsprojects.com/
+* Matplotlib :cite:p:`matplotlib`: used to produce figures, 
   http://matplotlib.org/
-* Setuptools: used to install the pecos package, https://setuptools.pypa.io/
+* Setuptools :cite:p:`setuptools`: used to install the pecos package, https://setuptools.pypa.io/
 
 Optional Python packages dependencies include:
 
-* minimalmodbus: used to collect data from a modbus device, 
+* minimalmodbus :cite:p:`minimalmodbus`: used to collect data from a modbus device, 
   https://minimalmodbus.readthedocs.io
-* sqlalchemy: used to insert data into a MySQL database,
+* sqlalchemy :cite:p:`sqlalchemy`: used to insert data into a MySQL database,
   https://www.sqlalchemy.org/
-* pyyaml: used to store configuration options in human readable data format,
+* pyyaml :cite:p:`pyyaml`: used to store configuration options in human readable data format,
   http://pyyaml.org/
-* PVLIB [SHFH16]_: used to simulate the performance of photovoltaic energy systems,
+* PVLIB :cite:p:`pvlib`: used to simulate the performance of photovoltaic energy systems,
   http://pvlib-python.readthedocs.io/
-* Plotly [SPHC16]_: used to produce interactive scalable figures, 
+* Plotly :cite:p:`plotly`: used to produce interactive scalable figures, 
   https://plot.ly/
 
 All other dependencies are part of the Python Standard Library.

documentation/installation.rst

@@ -9,7 +9,7 @@ and generate reports which include performance metrics, test results, and graphi
 The software can be customized for specific applications. 
 Some high-level features include:
 
-* Pecos uses Pandas DataFrames [Mcki13]_ to store and analyze time series data.  This dependency 
+* Pecos uses Pandas DataFrames :cite:p:`pandas` to store and analyze time series data.  This dependency 
   facilitates a wide range of analysis options and date-time functionality.
 
 * Data column names can be easily reassigned to common names through the use of a

documentation/overview.rst

@@ -342,7 +342,7 @@ Custom streaming analysis can be run using the following example.
 The custom function below, ``nearest_neighbor``, determines if the current data point is within 3 standard 
 deviations of data in a 10 minute history window.  
 In this case, metadata returns the distance from each column in the current data point to its nearest neighbor in the history.
-This is similar to the multivariate nearest neighbor algorithm used in CANARY [HMKC07]_.
+This is similar to the multivariate nearest neighbor algorithm used in CANARY :cite:p:`canary`.
 
 .. doctest::
     :hide:

documentation/qc_tests.rst

@@ -1,33 +1,27 @@
-References
-==============
-..
-	Citations begins with 4 letters:
-		one author: first 4 letters of name
-		two authors: first 2 letters of author1, first 2 letters of author 2
-		three authors: first 2 letters of author1, first letter of author 2, first letter of author 3
-		four authors: first letter of each author
-		more than four authors: first letter of first four authors
-	
-	The next two digits are the year (century ignored)
-	
-	If the 6 digits match another citation, add a lower case letter (a, b, ...)
+.. raw:: latex
 
-.. [HMKC07] Hart, D., McKenna, S.A., Klise, K., Cruz, V., & Wilson, M. (2007) Water quality event detection systems for drinking water contamination warning systems: Development testing and application of CANARY, World Environmental and Water Resources Congress (EWRI), Tampa, FL, May 15-19.
+    \clearpage
 
-.. [Hunt07] Hunter, J.D. (2007). Matplotlib: A 2D graphics environment. Computing in Science & Engineering, 3(9), 90-95.
+.. only:: html
 
-.. [KlSt16a] Klise, K.A., Stein, J.S. (2016). Performance Monitoring using Pecos, Technical Report SAND2016-3583, Sandia National Laboratories.
+    References
+    ==========
 
-.. [KlSt16b] Klise, K.A., Stein, J.S. (2016). Automated Performance Monitoring for PV Systems using Pecos, 43th Photovoltaic Specialists Conference (PVSC), Portland, OR, June 5-10.
+.. raw:: latex
 
-.. [KlSC17] Klise, K.A., Stein, J.S., Cunningham, J. (2017). Application of IEC 61724 Standards to Analyze PV System Performance in Different Climates, 44th Photovoltaic Specialists Conference (PVSC), Washington, DC, June 25-30.
+    \begingroup
+    \def\section#1#2{}
+    \def\chapter#1#2{}
+    \begin{thebibliography}{1234}
 
-.. [Mcki13] McKinney W. (2013). Python for Data Analysis: Data Wrangling with Pandas, NumPy, and IPython. O'Reilly Media, 1 edition, 466P.
+.. raw:: html
 
-.. [Rona08] Ronacher, A. (2008). Template Designer Documentation, http://jinja.pocoo.org/docs/dev/templates/ accessed July 1, 2016.
+    <div>
 
-.. [SHFH16] Stein, J.S., Holmgren, W.F., Forbess, J., & Hansen, C.W. (2016). PVLIB: Open Source Photovoltaic Performance Modeling Functions for Matlab and Python, 43rd Photovoltaic Specialists Conference (PVSC), Portland, OR, June 5-10.
+.. bibliography::
 
-.. [SPHC16] Sievert, C., Parmer, C., Hocking, T., Chamberlain, S., Ram, K., Corvellec, M., and Despouy, P. (2016). plotly: Create interactive web graphics via Plotly’s JavaScript graphing library [Software].
 
-.. [VaCV11] van der Walt, S., Colbert, S.C., & Varoquaux, G. (2011). The NumPy array: A structure for efficient numerical computation. Computing in Science & Engineering, 13, 22-30.
+.. raw:: latex
+
+    \end{thebibliography}
+    \endgroup

documentation/reference.rst

@@ -0,0 +1,131 @@
+@techreport{klise16a,
+  title={{Performance Monitoring using Pecos}},
+  author={Klise, Katherine A and Stein, Joshua S},
+  year={2016},
+  number = {SAND2016-3583},
+  institution={Sandia National Laboratories, Albuquerque, NM}
+}
+
+@inproceedings{klise16b,
+  title={{Automated performance monitoring for PV systems using Pecos}},
+  author={Klise, Katherine A and Stein, Joshua S},
+  booktitle={{2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}},
+  pages={3431--3435},
+  year={2016},
+  organization={IEEE}
+}
+
+@inproceedings{klise17,
+  title={{Application of IEC 61724 standards to analyze PV system performance in different climates}},
+  author={Klise, Katherine A and Stein, Joshua S and Cunningham, Joseph},
+  booktitle={{2017 IEEE 44th Photovoltaic Specialists Conference (PVSC)}},
+  pages={3161--3166},
+  year={2017},
+  organization={IEEE}
+}
+
+@techreport{wrf24,
+  title={{Integration of High-Frequency Performance Data for Microbial and Chemical Compound Control in Potable Reuse Treatment Systems}},
+  author={Pecson, Brian and Pisarenko, Aleks and Walker, Troy},
+  year={2024},
+  number = {Project #4954},
+  institution={Water Research Foundation, Alexandria, VA}
+}
+
+@inproceedings{canary,
+  title={{CANARY: A water quality event detection algorithm development tool}},
+  author={Hart, David and McKenna, Sean A and Klise, Katherine and Cruz, Victoria and Wilson, Mark},
+  booktitle={{World Environmental and Water Resources Congress 2007: Restoring Our Natural Habitat}},
+  pages={1--9},
+  year={2007}
+}
+
+@article{matplotlib,
+  author={Hunter, John D},
+  title={{Matplotlib: A 2D graphics environment}},
+  journal={Computing in Science \& Engineering},
+  volume={9},
+  number={03},
+  pages={90--95},
+  year={2007},
+  publisher={IEEE Computer Society}
+}
+
+@inproceedings{pandas,
+  author    = {McKinney, Wes},
+  title     = {{Data structures for statistical computing in Python}},
+  booktitle = {{Proceedings of the 9th Python in Science Conference}},
+  pages     = {56 - 61},
+  year      = {2010},
+  editor    = {St\'efan van der Walt and Jarrod Millman},
+}
+
+@inproceedings{pvlib,
+  author={Stein, Joshua S and Holmgren, William F and Forbess, Jessica and Hansen, Clifford W},
+  title={{PVLIB: Open source photovoltaic performance modeling functions for Matlab and Python}},
+  booktitle={{2016 IEEE 43rd Photovoltaic Specialists Conference (PVSC)}},
+  pages={3425--3430},
+  year={2016},
+  organization={IEEE}
+}
+
+@online{plotly, 
+  author = {Plotly Technologies Inc.}, 
+  title = {{Collaborative data science}}, 
+  publisher = {Plotly Technologies Inc.}, 
+  address = {Montreal, QC}, 
+  year = {2015}, 
+  url = {https://plot.ly} 
+}
+
+@article{numpy,
+  author  = {Charles R. Harris and K. Jarrod Millman and St{\'{e}}fan J.
+  van der Walt and Ralf Gommers and Pauli Virtanen and David
+  Cournapeau and Eric Wieser and Julian Taylor and Sebastian
+  Berg and Nathaniel J. Smith and Robert Kern and Matti Picus
+  and Stephan Hoyer and Marten H. van Kerkwijk and Matthew
+  Brett and Allan Haldane and Jaime Fern{\'{a}}ndez del
+  R{\'{i}}o and Mark Wiebe and Pearu Peterson and Pierre
+  G{\'{e}}rard-Marchant and Kevin Sheppard and Tyler Reddy and
+  Warren Weckesser and Hameer Abbasi and Christoph Gohlke and
+  Travis E. Oliphant},
+  title = {{Array programming with NumPy}},
+  year = {2020},
+  month = sep,
+  journal = {Nature},
+  volume = {585},
+  number = {7825},
+  pages = {357--362},
+  doi  = {10.1038/s41586-020-2649-2},
+  publisher = {Springer Science and Business Media {LLC}},
+}
+
+@online{sqlalchemy,
+  author = {Bayer, Michael},
+  title = {{The Architecture of Open Source Applications (Volume 2) SQLAlchemy}},
+  url  = {https://aosabook.org/en/v2/sqlalchemy.html}
+}
+
+@online{minimalmodbus,
+  author = {Berg, Jonas and others},
+  title = {{MinimalModbus}},
+  url  = {https://minimalmodbus.readthedocs.io/en/stable/authors.html}
+}
+
+@online{pyyaml,
+  author = {Simonov, Kirill and others},
+  title = {PyYAML},
+  url  = {https://github.com/yaml/pyyaml/graphs/contributors}
+}
+
+@online{jinja, 
+  author = {Ronacher, Armin and others}, 
+  title = {Jinja}, 
+  url = {https://github.com/pallets/jinja/graphs/contributors} 
+}
+
+@online{setuptools, 
+  author = {Eby, Phillip and Ippolito, Bob and others}, 
+  title = {Setuptools}, 
+  url = {https://setuptools.pypa.io/en/latest/history.html#credits} 
+}