CSSFrancis · hakonanes · May 13, 2024 · May 12, 2024 · May 12, 2024 · May 12, 2024
diff --git a/.gitignore b/.gitignore
@@ -69,7 +69,9 @@ instance/
 
 # Sphinx documentation
 doc/build/
+doc/examples/
 doc/reference/generated/
+doc/sg_execution_times.rst
 
 # PyBuilder
 target/

diff --git a/diffsims/libraries/diffraction_library.py b/diffsims/libraries/diffraction_library.py
@@ -172,7 +172,7 @@ def pickle_library(self, filename):
 
         See Also
         --------
-        load_DiffractionLibrary()
+        load_DiffractionLibrary
 
         """
         with open(filename, "wb") as handle:

diff --git a/diffsims/libraries/vector_library.py b/diffsims/libraries/vector_library.py
@@ -42,7 +42,7 @@ def load_VectorLibrary(filename, safety=False):
 
     See Also
     --------
-    VectorLibrary.pickle_library()
+    VectorLibrary.pickle_library
     """
     if safety:
         with open(filename, "rb") as handle:
@@ -92,7 +92,7 @@ def pickle_library(self, filename):
 
         See Also
         --------
-            load_VectorLibrary()
+        load_VectorLibrary
 
         """
         with open(filename, "wb") as handle:

diff --git a/doc/Makefile b/doc/Makefile
@@ -14,6 +14,12 @@ help:
 
 .PHONY: help Makefile
 
+clean:
+	rm -rf $(BUILDDIR)
+	rm -rf $(SOURCEDIR)/examples
+	rm -rf $(SOURCEDIR)/reference/generated
+	rm sg_execution_times.rst
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

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
@@ -39,12 +39,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
     "sphinx.ext.mathjax",
-    "sphinx.ext.napoleon",
     "sphinx_design",
     "sphinx_gallery.gen_gallery",
 ]
@@ -74,7 +74,7 @@
     "github_url": "https://github.com/pyxem/diffsims",
     "header_links_before_dropdown": 6,
     "logo": {"alt_text": project, "text": project},
-    "navigation_with_keys": False,
+    "navigation_with_keys": True,
     "show_toc_level": 2,
     "use_edit_page_button": True,
 }
@@ -172,8 +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
diff --git a/doc/index.rst b/doc/index.rst
@@ -12,47 +12,6 @@ diffsims is an open-source Python library for simulating diffraction.
     reference/index.rst
     dev/index.rst
     changelog.rst
-    Examples <examples/index>
-
-.. See: https://sphinx-design.readthedocs.io/en/furo-theme/grids.html
-.. grid:: 2
-    :gutter: 2
-
-    .. grid-item-card::
-        :link: https://github.com/pyxem/diffsims-demos
-
-        :octicon:`book;2em;sd-text-info` Tutorials
-        ^^^
-
-        In-depth guides for using diffsims.
-
-    .. grid-item-card::
-        :link: reference/index
-        :link-type: doc
-
-        :octicon:`code;2em;sd-text-info` API reference
-        ^^^
-
-        Descriptions of all functions, modules, and objects in diffsims.
-
-    .. grid-item-card::
-        :link: dev/index
-        :link-type: doc
-
-        :octicon:`people;2em;sd-text-info` Contributing
-        ^^^
-
-        Guide for contributing to diffsims.
-
-    .. grid-item-card::
-        :link: dev/examples
-        :link-type: doc
-
-        :octicon:`zap;2em;sd-text-info` Examples
-        ^^^
-
-        Gallery of short examples illustrating simple tasks that can be performed with diffsims.
-
 
 
 Installation
@@ -77,14 +36,51 @@ diffsims can be installed with `pip <https://pypi.org/project/diffsims>`__ or
 
 Further details are available in the :doc:`installation guide <user/installation>`.
 
+
 Learning resources
 ==================
 
+.. See: https://sphinx-design.readthedocs.io/en/furo-theme/grids.html
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card::
+        :link: https://github.com/pyxem/diffsims-demos
+
+        :octicon:`book;2em;sd-text-info` Tutorials
+        ^^^
+
+        In-depth guides for using diffsims (notebooks hosted on GitHub).
+
+    .. grid-item-card::
+        :link: examples/index
+        :link-type: doc
+
+        :octicon:`zap;2em;sd-text-info` Examples
+        ^^^
 
+        Short examples illustrating simple tasks that can be performed with diffsims.
+
+    .. grid-item-card::
+        :link: reference/index
+        :link-type: doc
+
+        :octicon:`code;2em;sd-text-info` API reference
+        ^^^
+
+        Descriptions of all functions, modules, and objects in diffsims.
+
+    .. grid-item-card::
+        :link: dev/index
+        :link-type: doc
+
+        :octicon:`people;2em;sd-text-info` Contributing
+        ^^^
 
         diffsims is a community project maintained for and by its users. There are many
         ways you can help!
 
+
 Citing diffsims
 ===============
 

diff --git a/doc/user/index.rst b/doc/user/index.rst
@@ -2,9 +2,6 @@
 User guide
 ==========
 
-See the `demos <https://github.com/pyxem/diffsims-demos>`_ for how to
-use diffsims.
-
 .. toctree::
     :caption: Getting started
     :maxdepth: 1
@@ -13,11 +10,11 @@ use diffsims.
 
 .. toctree::
     :caption: Usage
-    :maxdepth: 2
-    https://github.com/pyxem/diffsims-demos
+    :maxdepth: 3
+
+    Tutorials <https://github.com/pyxem/diffsims-demos>
     ../examples/index.rst
 
-    installation.rst
 .. toctree::
     :caption: Resources
 

diff --git a/examples/README.rst b/examples/README.rst
@@ -1,6 +1,7 @@
 .. _examples-index:
 
-Gallery of Examples
-===================
+========
+Examples
+========
 
 Below is a gallery of examples for different operations in diffsims.
diff --git a/setup.py b/setup.py
@@ -27,6 +27,7 @@
 # fmt: off
 extra_feature_requirements = {
     "doc": [
+        "numpydoc",
         "pydata-sphinx-theme",
         "sphinx                 >= 3.0.2",
         "sphinx-design",