Adds devops documentation page for deprecations

Author: echedey-ls

.gitignore

@@ -39,8 +39,8 @@ pvlib/spa_c_files/spa.h
 pvlib/spa_c_files/spa_tester.c
 
 # generated documentation
+docs/sphinx/source/contributing/generated
 docs/sphinx/source/reference/generated
-docs/sphinx/source/reference/*/generated
 docs/sphinx/source/savefig
 docs/sphinx/source/gallery
 docs/sphinx/source/sg_execution_times.rst

docs/sphinx/source/contributing/devops.rst

@@ -0,0 +1,73 @@
+.. _devops:
+
+Development Operations
+======================
+
+This page provides information on specific development needs found in the pvlib-python ecosystem. Some specific Python concepts may be used in this section.
+
+Deprecations
+------------
+Let's start by what is a deprecation: sometimes, a feature in the library is no longer needed because it has been superceded by better altenatives, or because better practices are considred beneficial. In this case, just doing that change (a removal, a rename) will probably be a **breaking change** for a number of users. Both developers and users desire to not get their code broken after a release in normal circumstances. There are a number of approaches to make these changes gradually, so at least there is some time in-between to warn about upcoming changes and to allow users to adapt their code.
+
+There are two ways to warn about upcoming changes:
+
+- Passively, by expecting users to read whatsnew entries, new version announcements on the mailing list, or by keeping a close eye on the repo activity.
+- Actively, via raising warnings with specific instructions when any of these deprecated features are used.
+
+While the pros for the latter are almost obvious, there is a main weakness; it imposes a number of extra steps to take and more code to maintain by the developers. This guide strives to close that gap.
+
+pvlib's submodule :py:mod:`pvlib._deprecation` has some utilities to ease the implementation of deprecations.
+
+Deprecation Warnings and Messages
+---------------------------------
+This is about the ``Exception`` that gets raised, but quickly dismished by the interpreter after logging. They automatically leave a text trace in the output buffer (console) so it can be seen by the user. In code terms, the following line raises a warning:
+
+.. code-block::
+
+    import warnings
+
+    warnings.warn("This feature is deprecated!")
+
+As a general rule, try to be concise on what the problem is and how to fix that. By default, Python will automatically inform about where the issue was found (although that can be modified, again in code terms, by setting a custom ``stacklevel`` in the warning factory).
+
+List of pvlib deprecation helpers
+---------------------------------
+
+.. py:module:: pvlib._deprecation
+
+.. currentmodule:: pvlib
+
+.. autosummary::
+   :toctree: generated/
+
+   _deprecation.deprecated
+   _deprecation.renamed_kwarg_warning
+   _deprecation.renamed_key_items_warning
+
+Know your deprecation helper
+----------------------------
+Remember to import the submodule.
+
+.. code-block::
+
+    from pvlib import _deprecation
+
+.. contents:: Table of Contents
+    :local:
+
+Deprecate a function
+~~~~~~~~~~~~~~~~~~~~
+See :py:func:`pvlib._deprecation.deprecated`.
+
+Rename keyword parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Applies both to *positional-or-keyword* parameters and *keyword-only* parameters.
+You can check out the differences at the `Python docs glossary <https://docs.python.org/3/glossary.html#term-parameter>`_.
+
+See :py:func:`pvlib._deprecation.renamed_kwarg_warning`.
+
+Rename an item from a collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For example, the key an item uses in a dictionary, the column in a ``pandas.DataFrame`` or any key-indexed object. Intended for objects returned by pvlib functions in the public API.
+
+See :py:func:`pvlib._deprecation.renamed_key_items_warning`

docs/sphinx/source/contributing/index.rst

@@ -12,3 +12,4 @@ Contributing
    how_to_contribute_new_code
    style_guide
    testing
+   devops

pvlib/_deprecation.py

@@ -169,14 +169,15 @@ def warn_deprecated(
         obj_type='attribute', addendum='', removal=''):
     """
     Used to display deprecation in a standard way.
+
     Parameters
     ----------
     since : str
         The release at which this API became deprecated.
     message : str, optional
         Override the default deprecation message.  The format
-        specifier `%(name)s` may be used for the name of the function,
-        and `%(alternative)s` may be used in the deprecation message
+        specifier ``%(name)s`` may be used for the name of the function,
+        and ``%(alternative)s`` may be used in the deprecation message
         to insert the name of an alternative to the deprecated
         function.  `%(obj_type)s` may be used to insert a friendly name
         for the type of object being deprecated.
@@ -198,12 +199,14 @@ def warn_deprecated(
         The object type being deprecated.
     addendum : str, optional
         Additional text appended directly to the final message.
+
     Examples
     --------
-        Basic example::
-            # To warn of the deprecation of "matplotlib.name_of_module"
-            warn_deprecated('1.4.0', name='matplotlib.name_of_module',
-                            obj_type='module')
+    Basic example:
+
+    >>> # To warn of the deprecation of "pvlib.name_of_module"
+    >>> warn_deprecated('1.4.0', name='pvlib.name_of_module',
+    >>>                 obj_type='module')
     """
     message = '\n' + _generate_deprecation_message(
         since, message, name, alternative, pending, obj_type, addendum,
@@ -217,15 +220,16 @@ def deprecated(since, message='', name='', alternative='', pending=False,
                addendum='', removal=''):
     """
     Decorator to mark a function or a class as deprecated.
+
     Parameters
     ----------
     since : str
         The release at which this API became deprecated.  This is
         required.
     message : str, optional
         Override the default deprecation message.  The format
-        specifier `%(name)s` may be used for the name of the object,
-        and `%(alternative)s` may be used in the deprecation message
+        specifier ``%(name)s`` may be used for the name of the object,
+        and ``%(alternative)s`` may be used in the deprecation message
         to insert the name of an alternative to the deprecated
         object.
     name : str, optional
@@ -234,9 +238,11 @@ def deprecated(since, message='', name='', alternative='', pending=False,
         though this is useful in the case of renamed functions, where
         the new function is just assigned to the name of the
         deprecated function.  For example::
+
             def new_function():
                 ...
             oldFunction = new_function
+
     alternative : str, optional
         An alternative API that the user may use in place of the deprecated
         API.  The deprecation warning will tell the user about this alternative
@@ -251,12 +257,14 @@ def new_function():
         with *pending*.
     addendum : str, optional
         Additional text appended directly to the final message.
+
     Examples
     --------
-        Basic example::
-            @deprecated('1.4.0')
-            def the_function_to_deprecate():
-                pass
+    Basic example:
+
+    >>> @deprecated('1.4.0')
+    >>> def the_function_to_deprecate():
+    >>>     pass
     """
 
     def deprecate(obj, message=message, name=name, alternative=alternative,
@@ -335,7 +343,7 @@ def renamed_kwarg_warning(since, old_param_name, new_param_name, removal=""):
 
     .. note::
         Documentation for the function may updated to reflect the new parameter
-        name; it is suggested to add a |.. versionchanged::| directive.
+        name; it is suggested to add a ``.. versionchanged::`` directive.
 
     Parameters
     ----------