pvplabs · adriesse · Jan 28, 2025 · Oct 31, 2024 · Oct 31, 2024 · Oct 31, 2024
diff --git a/README.md b/README.md
@@ -38,15 +38,15 @@ Useful tools for photovoltaics and beyond!
 
 Latest news
 -----------
-2024-02-13: More proof that these tools are useful!  The module efficiency functions were put to good use in [this new study by Lelia Deville and her colleagues][101]: 
+2024-02-13: More proof that these tools are useful!  The module efficiency functions were put to good use in [this new study by Lelia Deville and her colleagues][101]:
 
 [101]: https://doi.org/10.1002/pip.3763
 
 
 Copyright
 ---------
 
-Copyright (c) 2019-2020 Anton Driesse, PV Performance Labs.
+Copyright (c) 2019-2025 Anton Driesse, PV Performance Labs.
 
 
 License

diff --git a/README_PYPI.md b/README_PYPI.md
@@ -0,0 +1,22 @@
+# PV Performance Labs Tools for Python
+
+*Useful tools for photovoltaics and beyond!*
+
+This package, ``pvpltools``, makes available a collection of useful
+software components and functions created by Anton Driesse of PV Performance Labs.
+Many were developed in the context of consulting or research projects,
+sometimes as a necessity, and sometimes just to make life easier.
+
+The aim of this package is to make life easier for people facing similar needs
+and thereby, in a small way, support the accelerated deployment of photovoltaic power systems.
+
+The current version of this package is found in the github repository
+`pvplabs/pvpltools <https://github.com/pvplabs/pvpltools>`_ .
+Prior to 2024, the code was made available in
+`adriesse/pvpltools-python <https://github.com/adriesse/pvpltools-python>`_ .
+This older repository will remain in place, but will not be updated.
+
+``pvpltools`` is compatible with and complementary to
+`pvlib python <https://pvlib-python.readthedocs.io>`_.
+
+
diff --git a/docs/api_reference/dataplusmeta.rst b/docs/api_reference/dataplusmeta.rst
@@ -2,8 +2,12 @@
 
 .. currentmodule:: pvpltools
 
-Data + Metadata manipulation utils
-==================================
+=======================
+DataPlusMeta data files
+=======================
+
+Utities to combine columnar data and relevant metadata in a single text
+file using a standard layout.
 
 .. autosummary::
    :toctree: generated/

diff --git a/docs/api_reference/iec61853.rst b/docs/api_reference/iec61853.rst
@@ -2,8 +2,24 @@
 
 .. currentmodule:: pvpltools
 
-IEC61853 Utils
-==============
+Energy rating (IEC 61853)
+=========================
+
+This module implements the energy rating calculations
+described in standard IEC 61853.
+
+The four main calculation steps are:
+
+    1. Calculate the angle-of-incidence correction using the functions:
+        - martin_ruiz()
+        - martin_ruiz_diffuse()
+    2. Evaluate the spectral factor using the functions:
+        - convert_to_banded()
+        - calc_spectral_factor()
+    3. Estimate the operating temperature using the function:
+        - faiman()
+    4. Determine the module efficiency using the class:
+        - BilinearInterpolator()
 
 .. autosummary::
    :toctree: generated/

diff --git a/docs/api_reference/index.rst b/docs/api_reference/index.rst
@@ -7,10 +7,9 @@ API Reference
 =============
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
 
-   dataplusmeta
-   iec61853
    module_efficiency
    power_conversion
+   iec61853
+   dataplusmeta
diff --git a/docs/api_reference/module_efficiency.rst b/docs/api_reference/module_efficiency.rst
@@ -2,8 +2,17 @@
 
 .. currentmodule:: pvpltools
 
-Module efficiency modelling
-===========================
+====================
+PV module efficiency
+====================
+
+This module contains implementations of several PV module efficiency models.
+
+These models have a common purpose, which is to predict the efficiency at
+maximum power point as a function of the main operating conditions:
+effective irradiance and module temperature.
+
+A function to fit any of these models to measurements is also provided.
 
 .. autosummary::
    :toctree: generated/

diff --git a/docs/api_reference/power_conversion.rst b/docs/api_reference/power_conversion.rst
@@ -5,6 +5,10 @@
 Power conversion
 ================
 
+This module provides useful functions related to power conversion for
+PV systems, including a flexible implementation of the ADR power loss
+model, also known as the ADR inverter model.
+
 .. autosummary::
    :toctree: generated/
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -19,7 +19,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "pvpltools"
-copyright = "2024, Anton Driesse"
+copyright = "2019-2025, Anton Driesse"
 author = "Anton Driesse"
 
 version = pvpltools.__version__
@@ -72,6 +72,8 @@
 sphinx_gallery_conf = {
     "examples_dirs": "../examples",
     "gallery_dirs": "_autogenerated_examples",
+    # 'subsection_order': ['../examples/module_efficiency',
+    #                      '../examples/dataplusmeta'],
     "filename_pattern": r"\.py",
     # directory where function/class granular galleries are stored
     'backreferences_dir': 'api_reference/generated/gallery_backreferences',

diff --git a/docs/contribute/contributing.rst b/docs/contribute/contributing.rst
@@ -1,9 +1,12 @@
 How to contribute
 =================
 
-Thanks for considering contributing to the project! We welcome contributions from
-everyone. Please read the following guidelines before contributing, and in case
-of any questions, don't hesitate to reach out.
+If you would like to contribute to this project,
+please consider creating an issue on github first,
+or contact the maintainer(s) by email to discuss.
+
+We try to follow the guidelines below ourselves
+and would expect the same from you!
 
 .. contents::
    :local:

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,10 +1,38 @@
-pvpltools documentation
-=======================
+PV Performance Labs Tools for Python
+=====================================
 
-Welcome to pvpltools documentation!
+*Useful tools for photovoltaics and beyond!*
+
+This package, ``pvpltools``, makes available a collection of useful
+software components and functions created by Anton Driesse of PV Performance Labs.
+Many were developed in the context of consulting or research projects,
+sometimes out of necessity, and sometimes just to make life easier.
+
+The aim of this package is to make life easier for other people facing similar needs
+and thereby, in a small way, support the accelerated deployment of photovoltaic power systems.
+
+The current version of this package is found in the github repository
+`pvplabs/pvpltools <https://github.com/pvplabs/pvpltools>`_ .
+Prior to 2024, the code was made available in
+`adriesse/pvpltools-python <https://github.com/adriesse/pvpltools-python>`_ .
+This older repository will remain in place, but will not be updated.
+
+``pvpltools`` is compatible with and complementary to
+`pvlib python <https://pvlib-python.readthedocs.io>`_.
+
+
+License
+-------
+
+`GPL-3.0 <https://github.com/pvplabs/pvpltools/blob/main/LICENSE>`_.
+Feel free to let us know if that causes any problems!
+
+
+Table of contents
+-----------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    user_guide/index
    api_reference/index

diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst
@@ -4,8 +4,16 @@
 User Guide
 ==========
 
+Currently, there are four groups of functions related to the topics:
+
+- PV module efficiency: modeling efficiency as a function of irradiance and temperature
+- power conversion: efficiency losses in inverters, but not limited to inverters
+- energy rating: the (evolving) IEC-61853 method for rating PV modules
+- DataPlusMeta: read and write columnar data together with important metadata in a human-readable text file
+
+
 .. toctree::
    :maxdepth: 2
 
-   installation
    quick-overview
+   installation
diff --git a/docs/user_guide/installation.rst b/docs/user_guide/installation.rst
@@ -1,8 +1,13 @@
 Installation
 ============
 
+``pvpltools`` needs some commonly used packages like ``numpy``, ``scipy`` and ``pandas``.
+Some functions also depend on ``pvlib`` or ``ruamel.yaml``.
+The examples use ``matplotlib`` and ``openpyxl`` (indirectly).
+
+
 To install ``pvpltools`` from PyPI, run:
 
 .. code-block:: bash
 
-    pip install -U pvpltools
+    pip install pvpltools
diff --git a/docs/user_guide/quick-overview.rst b/docs/user_guide/quick-overview.rst
@@ -1,9 +1,11 @@
 Quick overview
 ==============
 
-This project aims to allow for easy access to useful tools for photovoltaics.
-It is a collection of utilities created by PV Performance Labs.
-Users are encouraged to contribute to the project by submitting issues or pull
-requests, so please, don't hesitate to reach out!
+Currently, there are four groups of functions related to the topics:
+
+- PV module efficiency: modeling efficiency as a function of irradiance and temperature
+- power conversion: efficiency losses in inverters, but not limited to inverters
+- energy rating: the (evolving) IEC-61853 method for rating PV modules
+- DataPlusMeta: read and write columnar data together with important metadata in a human-readable text file
+
 
-.. @Anton TODO, add more content as desired. Update index.rst with filenames.
diff --git a/docs/whatsnews/0.0.0-pre-PyPI-release.rst b/docs/whatsnews/0.0.0-pre-PyPI-release.rst
@@ -1,22 +1,39 @@
-Updates prior to the first PyPI release
-========================================
+
+----
+
+
+----
+
+Historical notes
+================
+
+News items prior to the first PyPI release.
+
+2024-02-13
+^^^^^^^^^^
+
+* More proof that these tools are useful!
+  The module efficiency functions were put to good use in
+  `this new study by Lelia Deville and her colleagues
+  <https://doi.org/10.1002/pip.3763>`_.
+
 
 2021-10-17
-----------
+^^^^^^^^^^
 
 * New module ``power_conversion``, which introduces a function for calculating the ADR inverter model coefficients and more.
 
 2021-08-11
-----------
+^^^^^^^^^^
 
-* The IEC 61853 spectral factor function has a new option ``integration_limit``.  Explanations are provided in the doc string. 
+* The IEC 61853 spectral factor function has a new option ``integration_limit``.  Explanations are provided in the doc string.
 
 2020-12-02
-----------
+^^^^^^^^^^
 
 * Seven models and a model fitting function are now available, and the example code shows how to fit them to data and calculate rms error for comparisons. And of course there are nice graphs:
 
-- The new module ``module_efficiency.py`` now contains functions for:
+* The new module ``module_efficiency.py`` contains functions for:
     - the new ADR model
     - HEY
     - MotherPV
@@ -27,7 +44,7 @@ Updates prior to the first PyPI release
     - fitting any of the models to measurements
 
 2020-02-29
-----------
+^^^^^^^^^^
 
-- The main building blocks for the Energy Rating calculation are complete.
-- A higher level function of example script may be coming some day.
+* The main building blocks for the Energy Rating calculation are complete.
+* A higher level function of example script may be coming some day.
diff --git a/docs/whatsnews/0.1.0.rst b/docs/whatsnews/0.1.0.rst
@@ -1,8 +1,6 @@
-v0.1.0
-======
-
-2024-15-01
+v0.1.0 (2025-02-01)
+===================
 
 * First official release of the project on PyPI.
+* Documentation published on readthedocs.org.
 
-.. note:: Feedback and contributions are welcome!
diff --git a/docs/whatsnews/0.1.0a.rst b/docs/whatsnews/0.1.0a.rst
@@ -1,4 +1,4 @@
-v0.1.0a1 - v0.1.0a2
+v0.1.0a1 - v0.1.0a3
 ===================
 
 - First alpha releases of the package through PyPI.
diff --git a/docs/whatsnews/_index.rst b/docs/whatsnews/_index.rst
@@ -4,7 +4,6 @@
 Changelog
 =========
 
-.. include:: _next_release.rst
 .. include:: 0.1.0.rst
 .. include:: 0.1.0a.rst
 .. include:: 0.0.0-pre-PyPI-release.rst
diff --git a/examples/300_module_efficiency/README.rst b/examples/300_module_efficiency/README.rst
@@ -0,0 +1,5 @@
+PV Module Efficiency
+--------------------
+
+Using functions in the
+:py:mod:`pvpltools.module_efficiency` submodule.
diff --git a/...dule_efficiency/module_efficiency_demo.py → ...dule_efficiency/module_efficiency_demo.py b/...dule_efficiency/module_efficiency_demo.py → ...dule_efficiency/module_efficiency_demo.py
@@ -2,7 +2,7 @@
 Module efficiency models
 ========================
 
-Primer on the :py:mod:`pvpltools.module_efficiency` submodule.
+Fit seven models to sample measurements and find the best one.
 """
 
 from pvpltools.module_efficiency import (

diff --git a/examples/800_dataplusmeta/README.rst b/examples/800_dataplusmeta/README.rst
@@ -0,0 +1,5 @@
+DataPlusMeta files:
+------------------
+
+Using functions in the
+:py:mod:`pvpltools.dataplusmeta` submodule.
diff --git a/examples/dataplusmeta/dataplusmeta_demo.py → ...les/800_dataplusmeta/dataplusmeta_demo.py b/examples/dataplusmeta/dataplusmeta_demo.py → ...les/800_dataplusmeta/dataplusmeta_demo.py
@@ -1,9 +1,8 @@
 """
-Using DataPlusMeta to read IEC 61853-1 matrix measurements
-==========================================================
+Using DataPlusMeta files
+========================
 
-This script demonstrates reading IEC 61853-1 matrix measurements
-stored in the DataPlusMeta format.
+Read a matrix of efficiency measurements and associated meta data.
 
 Copyright (c) 2019-2020 Anton Driesse, PV Performance Labs.
 """

diff --git a/examples/README.rst b/examples/README.rst
@@ -1,4 +1,5 @@
 Example Gallery
 ===============
 
-Here you will find examples on how to use the library. Feel free to contribute!
+Here you will find examples that demonstrate what various functions
+can do, and how to use them.
diff --git a/examples/dataplusmeta/README.rst b/examples/dataplusmeta/README.rst
diff --git a/examples/module_efficiency/README.rst b/examples/module_efficiency/README.rst