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

* Add docstring example * Update style_guide.rst Co-Authored-By: RDaxini <[email protected]> * Update style_guide.rst * Update style_guide.rst Co-Authored-By: Adam R. Jensen <[email protected]> * Update example_function_screenshot.png * Double check parameters Co-Authored-By: Ioannis Sifnaios <[email protected]> * datatypes Co-Authored-By: Ioannis Sifnaios <[email protected]> * Update interactive example Co-Authored-By: Ioannis Sifnaios <[email protected]> * Update example_function_screenshot.png * Add some little code to example Co-Authored-By: Adam R. Jensen <[email protected]> Co-Authored-By: Ioannis Sifnaios <[email protected]> * Update v0.11.2.rst * Apply suggestions from Cliff Co-authored-by: Cliff Hansen <[email protected]> * Update example_function_screenshot.png --------- Co-authored-by: RDaxini <[email protected]> Co-authored-by: Adam R. Jensen <[email protected]> Co-authored-by: Ioannis Sifnaios <[email protected]> Co-authored-by: Cliff Hansen <[email protected]>
pvlib · Oct 31, 2024 · e77714c · e77714c
1 parent 2a70f4b
commit e77714c
Show file tree

Hide file tree

Showing 3 changed files with 113 additions and 1 deletion.
diff --git a/docs/sphinx/source/_images/example_function_screenshot.png b/docs/sphinx/source/_images/example_function_screenshot.png
diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst
@@ -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

diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.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
 ~~~~~~~