Add numpydoc config (welcome, build warnings!), fix API minigallery

Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>
pyxem · May 12, 2024 · c6cf175 · c6cf175
1 parent 5f7ac67
commit c6cf175
Show file tree

Hide file tree

Showing 6 changed files with 43 additions and 7 deletions.
diff --git a/doc/_templates/custom-attribute-template.rst b/doc/_templates/custom-attribute-template.rst
@@ -3,3 +3,6 @@
 .. currentmodule:: {{ module }}
 
 .. autoproperty:: {{ objname }}
+
+.. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``
diff --git a/doc/_templates/custom-class-template.rst b/doc/_templates/custom-class-template.rst
@@ -7,12 +7,11 @@
     {% block attributes %}
     {% if attributes %}
     .. rubric:: {{ _('Attributes') }}
-
     .. autosummary::
         :toctree:
         :template: custom-attribute-template.rst
         {% for item in attributes %}
-        {% if item.0 != item.upper().0 and item not in inherited_members %}
+        {% if item.0 != item.upper().0 %}
         {{ name }}.{{ item }}
         {% endif %}
         {%- endfor %}
@@ -22,14 +21,16 @@
     {% block methods %}
     {% if methods %}
     .. rubric:: {{ _('Methods') }}
-
     .. autosummary::
         :toctree:
         :template: custom-method-template.rst
         {% for item in methods %}
-        {% if item != "__init__" and item not in inherited_members %}
+        {% if item.0 != item.upper().0 %}
         {{ name }}.{{ item }}
         {% endif %}
         {%- endfor %}
     {% endif %}
     {% endblock %}
+
+.. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``
diff --git a/doc/_templates/custom-function-template.rst b/doc/_templates/custom-function-template.rst
@@ -3,3 +3,6 @@
 .. currentmodule:: {{ module }}
 
 .. autofunction:: {{ objname }}
+
+.. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``
diff --git a/doc/_templates/custom-method-template.rst b/doc/_templates/custom-method-template.rst
@@ -3,3 +3,6 @@
 .. currentmodule:: {{ module }}
 
 .. automethod:: {{ objname }}
+
+.. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``
diff --git a/doc/_templates/custom-module-template.rst b/doc/_templates/custom-module-template.rst
@@ -60,8 +60,8 @@
     :toctree:
     :template: custom-module-template.rst
     :recursive:
-{% for item in modules %}
+    {% for item in modules %}
     {{ item }}
-{%- endfor %}
+    {%- endfor %}
 {% endif %}
 {% endblock %}
diff --git a/doc/conf.py b/doc/conf.py
@@ -172,7 +172,33 @@ def linkcode_resolve(domain, info):
     "examples_dirs": "../examples",  # path to your example scripts
     "gallery_dirs": "examples",  # path to where to save gallery generated output
     "filename_pattern": "^((?!sgskip).)*$",  # pattern to define which will be executed
-    "ignore_pattern": "_sgskip.py",  # pattern to define which will not be executed
     "reference_url": {"diffsims": None},
+    "run_stale_examples": False,
 }
 autosummary_generate = True
+
+
+# -- numpydoc
+# https://numpydoc.readthedocs.io
+numpydoc_show_class_members = False
+numpydoc_use_plots = True
+numpydoc_xref_param_type = True
+# fmt: off
+numpydoc_validation_checks = {
+    "all",   # All but the following:
+    "ES01",  # Not all docstrings need an extend summary
+    "EX01",  # Examples: Will eventually enforce
+    "GL01",  # Contradicts numpydoc examples
+    "GL02",  # Appears to be broken?
+    "GL07",  # Appears to be broken?
+    "GL08",  # Methods can be documented in super class
+    "PR01",  # Parameters can be documented in super class
+    "PR02",  # Properties with setters might have docstrings w/"Returns"
+    "PR04",  # Doesn't seem to work with type hints?
+    "RT01",  # Abstract classes might not have return sections
+    "SA01",  # Not all docstrings need a "See Also"
+    "SA04",  # "See Also" section does not need descriptions
+    "SS06",  # Not possible to make all summaries one line
+    "YD01",  # Yields: No plan to enforce
+}
+# fmt: on