[DOC]: Add docstring example to the contributing docs (#2254)

* Add docstring example * Update style_guide.rst Co-Authored-By: RDaxini <143435106+RDaxini@users.noreply.github.com> * Update style_guide.rst * Update style_guide.rst Co-Authored-By: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> * Update example_function_screenshot.png * Double check parameters Co-Authored-By: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com> * datatypes Co-Authored-By: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com> * Update interactive example Co-Authored-By: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com> * Update example_function_screenshot.png * Add some little code to example Co-Authored-By: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> Co-Authored-By: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com> * Update v0.11.2.rst * Apply suggestions from Cliff Co-authored-by: Cliff Hansen <cwhanse@sandia.gov> * Update example_function_screenshot.png --------- Co-authored-by: RDaxini <143435106+RDaxini@users.noreply.github.com> Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> Co-authored-by: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com> Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

Author: 5 people

docs/sphinx/source/_images/example_function_screenshot.png

@@ -163,7 +163,7 @@ An easy way to do this is with::
 
 Note: Anaconda users may have trouble using the above command to update an
 older version of docutils. If that happens, you can update it with ``conda``
-(e.g. ``conda install docutils=0.15.2``) and run the above command again.
+(e.g. ``conda install docutils=0.21``) and run the above command again.
 
 Once the ``doc`` dependencies are installed, navigate to ``/docs/sphinx`` and
 execute::
@@ -182,6 +182,116 @@ Note that Windows users need not have the ``make`` utility installed as pvlib
 includes a ``make.bat`` batch file that emulates its interface.
 
 
+.. _example-docstring:
+
+Example Docstring
+-----------------
+
+Here is a template for a function docstring that encapsulates the main
+features that may be used in any docstring. Note that not all sections are
+required for every function.
+
+.. code-block:: python
+
+ def example_function(poa_global, exponents, degree_symbol, time_ref='UT',
+ optional_arg=None):
+ r"""
+ One-sentence summary of the function (no citations).
+
+ A longer description of the function. This can include citations
+ (references) to literature [1]_, websites [2]_, and other code elements
+ such as functions (:py:func:`pvlib.location.lookup_altitude`) and
+ classes (:py:class:`pvlib.location.Location`).
+
+ .. versionadded:: 0.0.1
+ There are many more purpose-specific directives, admonitions and such
+ available at `this link <admonitions>`_. E.g.: ``.. versionchanged::``,
+ ``.. deprecated::``, ``.. note::`` and ``.. warning::``.
+
+ .. _admonitions: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings
+
+ Parameters
+ ----------
+ poa_global : numeric
+ Plane-of-array global irradiance, see :term:`poa_global`. [Wm⁻²].
+ exponents : array-like
+ A list of exponents. [x⁰¹²³⁴⁵⁶⁷⁸⁹⁻].
+ degree_symbol : pandas.Series or pandas.DataFrame
+ It's different from superscript zero. [°].
+ time_ref : ``'UT'`` or ``'TST'``, default: ``'UT'``
+ ``'UT'`` (universal time) or ``'TST'`` (True Solar Time).
+ optional_arg : integer, optional
+ A description of ``optional_arg``. [Unitless].
+
+ Specify a suitable datatype for each parameter. Other common
+ data types include ``str``, ``bool``, ``float``, ``numeric``
+ and ``pandas.DatetimeIndex``.
+
+ Returns
+ -------
+ name : numeric
+ A description of the return value.
+
+ Raises
+ ------
+ ValueError
+ If ``poa_global`` is negative.
+ KeyError
+ If ``time_ref`` does not exist.
+
+ Notes
+ -----
+ This section can include additional information about the function.
+
+ For example, an equation using LaTeX markup:
+
+ .. math::
+
+ a = \left(\frac{b}{c}\right)^2
+
+ where :math:`a` is the result of the equation, and :math:`b` and :math:`c`
+ are inputs.
+
+ Or a figure with a caption:
+
+ .. figure:: ../../_images/pvlib_logo_horiz.png
+ :scale: 10%
+ :alt: alternate text
+ :align: center
+
+ Figure caption.
+
+ See Also
+ --------
+ pvlib.location.lookup_altitude, pvlib.location.Location
+
+ Examples
+ --------
+ >>> example_function(1, 1, pd.Series([1]), "TST", 2)
+ 'Something'
+
+ References
+ ----------
+ A IEEE citation to a relevant reference. You may use an automatic
+ citation generator to format the citation correctly.
+
+ .. [1] Anderson, K., Hansen, C., Holmgren, W., Jensen, A., Mikofski, M.,
+ and Driesse, A. "pvlib python: 2023 project update." Journal of Open
+ Source Software, 8(92), 5994, (2023). :doi:`10.21105/joss.05994`.
+ .. [2] J. Smith and J. Doe. "Obama inaugurated as President." CNN.com.
+ Accessed: Feb. 1, 2009. [Online.]
+ Available: http://www.cnn.com/POLITICS/01/21/obama_inaugurated/index.html
+ """
+ a = "Some"
+ b = "thing"
+ return a + b
+
+A preview of how this docstring would render in the documentation can be seen in the
+following file: :download:`Example docstring<../_images/example_function_screenshot.png>`.
+
+Remember that to show the docstring in the documentation, you must list
+the function in the appropriate ``.rst`` file in the ``docs/sphinx/source/reference`` folder.
+
 .. _example-gallery:
 
 Example Gallery

docs/sphinx/source/contributing/style_guide.rst

@@ -25,6 +25,8 @@ Documentation
  page. (:issue:`2202`, :pull:`2226`)
 * Updated :py:func:`~pvlib.irradiance.reindl` to include definitions of terms
  and a new "notes" section (:issue:`2183`, :pull:`2193`)
+* Explained how to write docstrings for new functions in :ref:`example-docstring`
+ (:discussion:`2081`, :pull:`2254`)
 
 Testing
 ~~~~~~~