Fix more Sphinx issues

CFT-HY · Oct 25, 2023 · 6f75e8e · 6f75e8e
1 parent 49c91fb
commit 6f75e8e
Show file tree

Hide file tree

Showing 10 changed files with 71 additions and 12 deletions.
diff --git a/docs/_templates/module.rst b/docs/_templates/module.rst
@@ -1,3 +1,7 @@
+.. Please see these for ideas on how to expand this template
+   https://github.com/sphinx-doc/sphinx/issues/7912
+   https://sphinx-gallery.github.io/stable/configuration.html#auto-documenting-your-api-with-links-to-examples
+
 {{ fullname }}
 {{ underline }}
 
@@ -47,9 +51,21 @@
    Exceptions
    ----------
 
-   .. autosummary::
-   {% for item in exceptions %}
-      {{ item }}
+  {% for item in exceptions %}
+   .. autoexception:: {{ item }}
+
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+
+   Attributes
+   ----------
+
+  {% for item in attributes %}
+   .. autodata:: {{ item }}
 
    {%- endfor %}
    {% endif %}

diff --git a/docs/conf.py b/docs/conf.py
@@ -13,6 +13,7 @@
 import os.path
 import sys
 import typing as tp
+import warnings
 
 dir_path = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, os.path.dirname(dir_path))
@@ -108,10 +109,12 @@
 # -- Autodoc -----------------------------------------------------------------
 
 autodoc_default_options = {
-    "members": True,
+    # This would result in duplicate class descriptions when using a template.
+    # "members": True,
     "show-inheritance": True,
     "undoc-members": True,
 }
+autodoc_preserve_defaults = True
 autodoc_typehints = "description"
 
 
@@ -205,10 +208,24 @@
     "gallery_dirs": "auto_examples",
     "ignore_pattern": r"(__init__\.py|utils\.py)",
     # "image_srcset": ["2x"],
-    # "matplotlib_animations": True,
+    # "line_numbers": True,
+    "matplotlib_animations": True,
     "reference_url": {
         "pttools": None,
+        "tests": None,
     },
     "show_memory": True,
 }
 autosummary_generate = True
+
+
+# Remove matplotlib agg warnings from generated doc when using plt.show
+# From: https://github.com/sphinx-gallery/sphinx-gallery/blob/master/doc/conf.py
+warnings.filterwarnings(
+    "ignore",
+    category=UserWarning,
+    message="Matplotlib is currently using agg, which is a"
+    " non-GUI backend, so cannot show the figure.",
+)
+
+# numpydoc_show_class_members = False
diff --git a/docs/modules/misc.rst b/docs/modules/misc.rst
@@ -4,7 +4,9 @@ Other
 Logging
 -------
 .. automodule:: pttools.logging
+   :members:
 
 Type hints
 ----------
 .. automodule:: pttools.type_hints
+   :members:
diff --git a/docs/modules/tests/misc.rst b/docs/modules/tests/misc.rst
@@ -5,13 +5,16 @@ Examples
 --------
 
 .. automodule:: tests.test_examples
+   :members:
 
 Performance
 -----------
 
 .. automodule:: tests.test_performance
+   :members:
 
 Speedup
 -------
 
 .. automodule:: tests.test_speedup
+   :members:
diff --git a/docs/modules/tests/models.rst b/docs/modules/tests/models.rst
@@ -0,0 +1,21 @@
+Models
+======
+
+.. currentmodule:: tests.models
+
+.. automodule:: tests.models
+   :no-members:
+   :no-inherited-members:
+
+:py:mod:`tests.models`:
+
+.. autosummary::
+   :toctree: gen_modules/
+   :template: module.rst
+
+   base_bag
+   base_model
+   base_thermo
+   test_giese
+   test_models
+   test_sm
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,6 +1,6 @@
 memory-profiler >= 0.61.0
 # myst-parser
-sphinx >= 6.2.1
-sphinx-gallery >= 0.11.1
+sphinx >= 7.2.6
+sphinx-gallery >= 0.14.0
 sphinx-math-dollar >= 1.2.1
-sphinx-rtd-theme >= 1.0.0
+sphinx-rtd-theme >= 1.3.0
diff --git a/examples/plot_ke_frac.py b/examples/plot_ke_frac.py
@@ -1,6 +1,6 @@
 r"""
 Kinetic energy fraction
-===============
+=======================
 
 Plot the kinetic energy fraction for various $\alpha_n$ as a function of $\xi_\text{wall}$
 """

diff --git a/pttools/bubble/alpha.py b/pttools/bubble/alpha.py
@@ -259,7 +259,7 @@ def find_alpha_n_from_w_xi(w: np.ndarray, xi: np.ndarray, v_wall: float, alpha_p
     :param w: $w$ array of a bubble
     :param xi: $xi$ array of a bubble
     :param v_wall: $v_\text{wall}$
-    :param alpha_p. $\alpha_+$
+    :param alpha_p: $\alpha_+$
     :return: $\alpha_n$
     """
     n_wall = props.find_v_index(xi, v_wall)

diff --git a/pttools/models/sigmoid.py b/pttools/models/sigmoid.py
@@ -13,7 +13,7 @@ def sigmoid(
         midpoint: th.FloatOrArr,
         max_val: th.FloatOrArr,
         steepness: th.FloatOrArr) -> th.FloatOrArr:
-    """`Logistic function <https://en.wikipedia.org/wiki/Logistic_function>_"""
+    """`Logistic function <https://en.wikipedia.org/wiki/Logistic_function>`_"""
     return max_val / (1 + np.exp(-steepness*(x - midpoint)))
 
 

diff --git a/pttools/ssmtools/spectrum.py b/pttools/ssmtools/spectrum.py
@@ -334,7 +334,7 @@ def spec_den_gw_scaled(
     factor of 2.
 
     :return: $\hat{\mathcal{P}}$ Eq. 3.33 of Chloe's thesis, which should be ($3\Gamma \bar{U}_f$) Eq. 3.47
-    Eq. 3.46 converted to the spectral density and divided by (H L_f)
+        Eq. 3.46 converted to the spectral density and divided by (H L_f)
 
     The factor of 3 comes from the Friedmann equation
     3H^2/(8pi G)