[DOC]: sphinxcontrib-bibtex preview

docs/sphinx/source/citations.bib

@@ -0,0 +1,16 @@
+% Escape special LaTeX characters: & % $ # _ { } ~ ^ \ with a backslash in front of them
+% Except for unique entry indentifier
+
+@article{Anderson_Jensen_2024,
+  title        = {Shaded fraction and backtracking in single-axis trackers on rolling terrain},
+  volume       = {16},
+  issn         = {1941-7012},
+  doi          = {10.1063/5.0202220},
+  abstractnote = {A generalized closed-form equation for the shaded collector fraction in solar arrays on rolling or undulating terrain is provided for single-axis tracking and fixed-tilt systems. The equation accounts for different rotation angles between the shaded and shading trackers, cross-axis slope between the two trackers, and offset between the collector plane and axis of rotation. The validity of the equation is demonstrated through comparison with numerical ray-tracing simulations and remaining minor sources of error are quantified. Additionally, a simple procedure to determine backtracking rotations for each row in an array installed on the rolling terrain (varying in the direction perpendicular to the tracker axes) is provided. The backtracking equation accounts for a desired shaded fraction (including complete shade avoidance) as well as an axis-collector offset. Test cases are provided to facilitate implementation of these equations.},
+  number       = {2},
+  journal      = {Journal of Renewable and Sustainable Energy},
+  author       = {Anderson, Kevin S. and Jensen, Adam R.},
+  year         = {2024},
+  month        = apr,
+  pages        = {023504}
+}

docs/sphinx/source/conf.py

@@ -56,6 +56,7 @@
     'sphinx_gallery.gen_gallery',
     'sphinx_toggleprompt',
     'sphinx_favicon',
+    'sphinxcontrib.bibtex',
 ]
 
 mathjax3_config = {'chtml': {'displayAlign': 'left',
@@ -493,3 +494,14 @@ def make_github_url(file_name):
     'make_github_url': make_github_url,
     'edit_page_url_template': '{{ make_github_url(file_name) }}',
 }
+
+
+# -- sphinxcontrib-bibtex configuration -----------------------------------
+# https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html
+# bibtex_encoding = 'utf-8-sig'  # default
+# bibtex_default_style = 'alpha'  # default, https://www.overleaf.com/learn/latex/Bibtex_bibliography_styles  # noqa: E501
+# bibtex_reference_style = 'label'  # default
+# bibtex_foot_reference_style = 'foot'  # default, the only one provided
+# bibtex_tooltips = True  # default
+# bibtex_tooltips_style = bibtex_default_style  # default
+bibtex_bibfiles = ['citations.bib']

pvlib/shading.py

@@ -420,8 +420,9 @@ def shaded_fraction1d(
     .. figure:: ../../_images/Anderson_Jensen_2024_Fig3.png
         :alt: Diagram showing the two rows and the parameters of the model.
 
-        Figure 3 of [1]_. See correspondence between this nomenclature and the
-        function parameters in the table below.
+        Figure 3 of :footcite:`Anderson_Jensen_2024`. See correspondence
+        between this nomenclature and the function parameters in the table
+        below.
 
     +------------------+----------------------------+---------------------+
     | Symbol           | Parameter                  | Units               |
@@ -507,11 +508,9 @@ def shaded_fraction1d(
 
     References
     ----------
-    .. [1] Kevin S. Anderson, Adam R. Jensen; Shaded fraction and backtracking
-        in single-axis trackers on rolling terrain. J. Renewable Sustainable
-        Energy 1 March 2024; 16 (2): 023504. :doi:`10.1063/5.0202220`
+    .. footbibliography::
     """
-    # For nomenclature you may refer to [1].
+    # For nomenclature you may refer to [Anderson_Jensen_2024].
 
     # rotation of row casting the shadow defaults to shaded row's one
     if shading_row_rotation is None:
@@ -532,7 +531,7 @@ def shaded_fraction1d(
 
     cos_theta_2_S_diff_abs = np.abs(cosd(thetas_2_S_diff))
 
-    # Eq. (12) of [1]
+    # Eq. (12) of [Anderson_Jensen_2024]
     t_asterisk = (
         0.5
         + np.abs(cosd(thetas_1_S_diff)) / cos_theta_2_S_diff_abs / 2

pyproject.toml

@@ -65,6 +65,7 @@ doc = [
     'pillow',
     'sphinx-toggleprompt == 0.5.2',
     'sphinx-favicon',
+    'sphinxcontrib-bibtex == 2.6.2',
     'solarfactors',
 ]
 test = [