Add Documentation Examples

.gitignore

@@ -69,7 +69,9 @@ instance/
 
 # Sphinx documentation
 doc/build/
+doc/examples/
 doc/reference/generated/
+doc/sg_execution_times.rst
 
 # PyBuilder
 target/

MANIFEST.in

@@ -12,4 +12,5 @@ include setup.cfg
 include setup.py
 include diffsims/tests/**/*.npy
 
-recursive-include doc Makefile make.bat *.rst *.py *.png
+recursive-include doc Makefile make.bat *.rst *.py *.png
+recursive-include examples *.py *.rst

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:

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:

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

doc/_templates/custom-attribute-template.rst

@@ -3,3 +3,6 @@
 .. currentmodule:: {{ module }}
 
 .. autoproperty:: {{ objname }}
+
+.. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``

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 }}``

doc/_templates/custom-function-template.rst

@@ -3,3 +3,6 @@
 .. currentmodule:: {{ module }}
 
 .. autofunction:: {{ objname }}
+
+.. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``

doc/_templates/custom-method-template.rst

@@ -3,3 +3,6 @@
 .. currentmodule:: {{ module }}
 
 .. automethod:: {{ objname }}
+
+.. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``

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 %}

doc/conf.py

@@ -39,13 +39,14 @@
 # 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",
 ]
 
 # Create links to references within diffsims' documentation to these packages
@@ -73,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,
 }
@@ -162,3 +163,42 @@ def linkcode_resolve(domain, info):
 autodoc_default_options = {
     "show-inheritance": True,
 }
+
+# -- Sphinx-Gallery---------------
+# https://sphinx-gallery.github.io
+sphinx_gallery_conf = {
+    "backreferences_dir": "reference/generated",
+    "doc_module": ("diffsims",),
+    "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
+    "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

doc/index.rst

@@ -13,6 +13,7 @@ diffsims is an open-source Python library for simulating diffraction.
     dev/index.rst
     changelog.rst
 
+
 Installation
 ============
 
@@ -35,6 +36,7 @@ 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
 ==================
 
@@ -48,7 +50,16 @@ Learning resources
         :octicon:`book;2em;sd-text-info` Tutorials
         ^^^
 
-        In-depth guides for using diffsims.
+        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
@@ -69,6 +80,7 @@ Learning resources
         diffsims is a community project maintained for and by its users. There are many
         ways you can help!
 
+
 Citing diffsims
 ===============
 

doc/user/index.rst

@@ -2,15 +2,19 @@
 User guide
 ==========
 
-See the `demos <https://github.com/pyxem/diffsims-demos>`_ for how to
-use diffsims.
-
 .. toctree::
     :caption: Getting started
     :maxdepth: 1
 
     installation.rst
 
+.. toctree::
+    :caption: Usage
+    :maxdepth: 3
+
+    Tutorials <https://github.com/pyxem/diffsims-demos>
+    ../examples/index.rst
+
 .. toctree::
     :caption: Resources
 

examples/README.rst

@@ -0,0 +1,7 @@
+.. _examples-index:
+
+========
+Examples
+========
+
+Below is a gallery of examples for different operations in diffsims.

examples/creating_a_simulation_library/README.rst

@@ -0,0 +1,4 @@
+Creating a Simulation Library
+=============================
+
+These examples show specific workflows for creating a library of simulations.

examples/creating_a_simulation_library/migration_guide.py

@@ -0,0 +1,84 @@
+"""
+0.5.x --> 0.6.x Migration Guide
+===============================
+This is a migration guide for version 0.5.x to 0.6.x. This guide helps to show the changes
+that were made to the API and how to update your code to use the new API.
+
+Here you can see how to make an equivalent to a diffraction library
+
+Old
+---
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from diffpy.structure import Atom, Lattice, Structure
+
+from diffsims.libraries.structure_library import StructureLibrary
+from diffsims.generators.diffraction_generator import DiffractionGenerator
+from diffsims.generators.library_generator import DiffractionLibraryGenerator
+
+
+latt = Lattice(4, 4, 4, 90, 90, 90)
+atoms = [
+    Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
+    Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
+]
+structure_matrix = Structure(atoms=atoms, lattice=latt)
+euler_angles = np.array([[0, 0, 0], [10.0, 0.0, 0.0]])
+struct_library = StructureLibrary(["Al"], [structure_matrix], [euler_angles])
+diff_gen = DiffractionGenerator(accelerating_voltage=200)
+lib_gen = DiffractionLibraryGenerator(diff_gen)
+diff_lib = lib_gen.get_diffraction_library(
+    struct_library,
+    calibration=0.0262,
+    reciprocal_radius=1.6768,
+    half_shape=64,
+    with_direct_beam=True,
+    max_excitation_error=0.02,
+)
+
+# %%
+# New
+# ---
+
+from orix.crystal_map import Phase
+from orix.quaternion import Rotation
+from diffsims.generators.simulation_generator import SimulationGenerator
+
+latt = Lattice(4, 4, 4, 90, 90, 90)
+atoms = [
+    Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
+    Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
+]
+structure_matrix = Structure(atoms=atoms, lattice=latt)
+p = Phase("Al", point_group="m-3m", structure=structure_matrix)
+gen = SimulationGenerator(accelerating_voltage=200)
+rot = Rotation.from_euler([[0, 0, 0], [10.0, 0.0, 0.0]], degrees=True)
+sim = gen.calculate_diffraction2d(
+    phase=p,
+    rotation=rot,
+    reciprocal_radius=1.6768,
+    max_excitation_error=0.02,
+    with_direct_beam=True,
+)
+
+fig, axs = plt.subplots(2, 2, figsize=(10, 10))
+for i in range(2):
+    diff_lib["Al"]["simulations"][i].plot(
+        size_factor=15, show_labels=True, ax=axs[i, 0]
+    )
+    sim.irot[i].plot(ax=axs[i, 1], size_factor=15, show_labels=True)
+    axs[i, 0].set_xlim(-1.5, 1.5)
+    axs[i, 0].set_ylim(-1.5, 1.5)
+    axs[i, 1].set_xlim(-1.5, 1.5)
+    axs[i, 1].set_ylim(-1.5, 1.5)
+
+_ = axs[0, 0].set_title("Old")
+_ = axs[0, 1].set_title("New")
+
+# %%