Skip to content

Commit cc8b0a7

Browse files
hakonaneshakonanes
authored
Merge pull request #209 from CSSFrancis/add_examples
Add Documentation Examples
2 parents ddb903d + c6cf175 commit cc8b0a7

18 files changed

+289
-16
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,9 @@ instance/
6969

7070
# Sphinx documentation
7171
doc/build/
72+
doc/examples/
7273
doc/reference/generated/
74+
doc/sg_execution_times.rst
7375

7476
# PyBuilder
7577
target/

‎MANIFEST.in

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,5 @@ include setup.cfg
1212
include setup.py
1313
include diffsims/tests/**/*.npy
1414

15-
recursive-include doc Makefile make.bat *.rst *.py *.png
15+
recursive-include doc Makefile make.bat *.rst *.py *.png
16+
recursive-include examples *.py *.rst

‎diffsims/libraries/diffraction_library.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ def pickle_library(self, filename):
172172
173173
See Also
174174
--------
175-
load_DiffractionLibrary()
175+
load_DiffractionLibrary
176176
177177
"""
178178
with open(filename, "wb") as handle:

‎diffsims/libraries/vector_library.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ def load_VectorLibrary(filename, safety=False):
4242
4343
See Also
4444
--------
45-
VectorLibrary.pickle_library()
45+
VectorLibrary.pickle_library
4646
"""
4747
if safety:
4848
with open(filename, "rb") as handle:
@@ -92,7 +92,7 @@ def pickle_library(self, filename):
9292
9393
See Also
9494
--------
95-
load_VectorLibrary()
95+
load_VectorLibrary
9696
9797
"""
9898
with open(filename, "wb") as handle:

‎doc/Makefile

+6
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@ help:
1414

1515
.PHONY: help Makefile
1616

17+
clean:
18+
rm -rf $(BUILDDIR)
19+
rm -rf $(SOURCEDIR)/examples
20+
rm -rf $(SOURCEDIR)/reference/generated
21+
rm sg_execution_times.rst
22+
1723
# Catch-all target: route all unknown targets to Sphinx using the new
1824
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
1925
%: Makefile

‎doc/_templates/custom-attribute-template.rst

+3
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
.. currentmodule:: {{ module }}
44

55
.. autoproperty:: {{ objname }}
6+
7+
.. minigallery:: {{ module }}.{{ objname }}
8+
:add-heading: Examples using ``{{ objname }}``

‎doc/_templates/custom-class-template.rst

+5-4
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,11 @@
77
{% block attributes %}
88
{% if attributes %}
99
.. rubric:: {{ _('Attributes') }}
10-
1110
.. autosummary::
1211
:toctree:
1312
:template: custom-attribute-template.rst
1413
{% for item in attributes %}
15-
{% if item.0 != item.upper().0 and item not in inherited_members %}
14+
{% if item.0 != item.upper().0 %}
1615
{{ name }}.{{ item }}
1716
{% endif %}
1817
{%- endfor %}
@@ -22,14 +21,16 @@
2221
{% block methods %}
2322
{% if methods %}
2423
.. rubric:: {{ _('Methods') }}
25-
2624
.. autosummary::
2725
:toctree:
2826
:template: custom-method-template.rst
2927
{% for item in methods %}
30-
{% if item != "__init__" and item not in inherited_members %}
28+
{% if item.0 != item.upper().0 %}
3129
{{ name }}.{{ item }}
3230
{% endif %}
3331
{%- endfor %}
3432
{% endif %}
3533
{% endblock %}
34+
35+
.. minigallery:: {{ module }}.{{ objname }}
36+
:add-heading: Examples using ``{{ objname }}``

‎doc/_templates/custom-function-template.rst

+3
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
.. currentmodule:: {{ module }}
44

55
.. autofunction:: {{ objname }}
6+
7+
.. minigallery:: {{ module }}.{{ objname }}
8+
:add-heading: Examples using ``{{ objname }}``

‎doc/_templates/custom-method-template.rst

+3
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
.. currentmodule:: {{ module }}
44

55
.. automethod:: {{ objname }}
6+
7+
.. minigallery:: {{ module }}.{{ objname }}
8+
:add-heading: Examples using ``{{ objname }}``

‎doc/_templates/custom-module-template.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@
6060
:toctree:
6161
:template: custom-module-template.rst
6262
:recursive:
63-
{% for item in modules %}
63+
{% for item in modules %}
6464
{{ item }}
65-
{%- endfor %}
65+
{%- endfor %}
6666
{% endif %}
6767
{% endblock %}

‎doc/conf.py

+42-2
Original file line numberDiff line numberDiff line change
@@ -39,13 +39,14 @@
3939
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
4040
# ones.
4141
extensions = [
42+
"numpydoc",
4243
"sphinx.ext.autodoc",
4344
"sphinx.ext.autosummary",
4445
"sphinx.ext.intersphinx",
4546
"sphinx.ext.linkcode",
4647
"sphinx.ext.mathjax",
47-
"sphinx.ext.napoleon",
4848
"sphinx_design",
49+
"sphinx_gallery.gen_gallery",
4950
]
5051

5152
# Create links to references within diffsims' documentation to these packages
@@ -73,7 +74,7 @@
7374
"github_url": "https://github.com/pyxem/diffsims",
7475
"header_links_before_dropdown": 6,
7576
"logo": {"alt_text": project, "text": project},
76-
"navigation_with_keys": False,
77+
"navigation_with_keys": True,
7778
"show_toc_level": 2,
7879
"use_edit_page_button": True,
7980
}
@@ -162,3 +163,42 @@ def linkcode_resolve(domain, info):
162163
autodoc_default_options = {
163164
"show-inheritance": True,
164165
}
166+
167+
# -- Sphinx-Gallery---------------
168+
# https://sphinx-gallery.github.io
169+
sphinx_gallery_conf = {
170+
"backreferences_dir": "reference/generated",
171+
"doc_module": ("diffsims",),
172+
"examples_dirs": "../examples", # path to your example scripts
173+
"gallery_dirs": "examples", # path to where to save gallery generated output
174+
"filename_pattern": "^((?!sgskip).)*$", # pattern to define which will be executed
175+
"reference_url": {"diffsims": None},
176+
"run_stale_examples": False,
177+
}
178+
autosummary_generate = True
179+
180+
181+
# -- numpydoc
182+
# https://numpydoc.readthedocs.io
183+
numpydoc_show_class_members = False
184+
numpydoc_use_plots = True
185+
numpydoc_xref_param_type = True
186+
# fmt: off
187+
numpydoc_validation_checks = {
188+
"all", # All but the following:
189+
"ES01", # Not all docstrings need an extend summary
190+
"EX01", # Examples: Will eventually enforce
191+
"GL01", # Contradicts numpydoc examples
192+
"GL02", # Appears to be broken?
193+
"GL07", # Appears to be broken?
194+
"GL08", # Methods can be documented in super class
195+
"PR01", # Parameters can be documented in super class
196+
"PR02", # Properties with setters might have docstrings w/"Returns"
197+
"PR04", # Doesn't seem to work with type hints?
198+
"RT01", # Abstract classes might not have return sections
199+
"SA01", # Not all docstrings need a "See Also"
200+
"SA04", # "See Also" section does not need descriptions
201+
"SS06", # Not possible to make all summaries one line
202+
"YD01", # Yields: No plan to enforce
203+
}
204+
# fmt: on

‎doc/index.rst

+13-1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ diffsims is an open-source Python library for simulating diffraction.
1313
dev/index.rst
1414
changelog.rst
1515

16+
1617
Installation
1718
============
1819

@@ -35,6 +36,7 @@ diffsims can be installed with `pip <https://pypi.org/project/diffsims>`__ or
3536
3637
Further details are available in the :doc:`installation guide <user/installation>`.
3738

39+
3840
Learning resources
3941
==================
4042

@@ -48,7 +50,16 @@ Learning resources
4850
:octicon:`book;2em;sd-text-info` Tutorials
4951
^^^
5052

51-
In-depth guides for using diffsims.
53+
In-depth guides for using diffsims (notebooks hosted on GitHub).
54+
55+
.. grid-item-card::
56+
:link: examples/index
57+
:link-type: doc
58+
59+
:octicon:`zap;2em;sd-text-info` Examples
60+
^^^
61+
62+
Short examples illustrating simple tasks that can be performed with diffsims.
5263

5364
.. grid-item-card::
5465
:link: reference/index
@@ -69,6 +80,7 @@ Learning resources
6980
diffsims is a community project maintained for and by its users. There are many
7081
ways you can help!
7182

83+
7284
Citing diffsims
7385
===============
7486

‎doc/user/index.rst

+7-3
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,19 @@
22
User guide
33
==========
44

5-
See the `demos <https://github.com/pyxem/diffsims-demos>`_ for how to
6-
use diffsims.
7-
85
.. toctree::
96
:caption: Getting started
107
:maxdepth: 1
118

129
installation.rst
1310

11+
.. toctree::
12+
:caption: Usage
13+
:maxdepth: 3
14+
15+
Tutorials <https://github.com/pyxem/diffsims-demos>
16+
../examples/index.rst
17+
1418
.. toctree::
1519
:caption: Resources
1620

‎examples/README.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _examples-index:
2+
3+
========
4+
Examples
5+
========
6+
7+
Below is a gallery of examples for different operations in diffsims.

‎examples/creating_a_simulation_library/README.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Creating a Simulation Library
2+
=============================
3+
4+
These examples show specific workflows for creating a library of simulations.

‎examples/creating_a_simulation_library/migration_guide.py

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
"""
2+
0.5.x --> 0.6.x Migration Guide
3+
===============================
4+
This is a migration guide for version 0.5.x to 0.6.x. This guide helps to show the changes
5+
that were made to the API and how to update your code to use the new API.
6+
7+
Here you can see how to make an equivalent to a diffraction library
8+
9+
Old
10+
---
11+
"""
12+
13+
import numpy as np
14+
import matplotlib.pyplot as plt
15+
from diffpy.structure import Atom, Lattice, Structure
16+
17+
from diffsims.libraries.structure_library import StructureLibrary
18+
from diffsims.generators.diffraction_generator import DiffractionGenerator
19+
from diffsims.generators.library_generator import DiffractionLibraryGenerator
20+
21+
22+
latt = Lattice(4, 4, 4, 90, 90, 90)
23+
atoms = [
24+
Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
25+
Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
26+
Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
27+
Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
28+
]
29+
structure_matrix = Structure(atoms=atoms, lattice=latt)
30+
euler_angles = np.array([[0, 0, 0], [10.0, 0.0, 0.0]])
31+
struct_library = StructureLibrary(["Al"], [structure_matrix], [euler_angles])
32+
diff_gen = DiffractionGenerator(accelerating_voltage=200)
33+
lib_gen = DiffractionLibraryGenerator(diff_gen)
34+
diff_lib = lib_gen.get_diffraction_library(
35+
struct_library,
36+
calibration=0.0262,
37+
reciprocal_radius=1.6768,
38+
half_shape=64,
39+
with_direct_beam=True,
40+
max_excitation_error=0.02,
41+
)
42+
43+
# %%
44+
# New
45+
# ---
46+
47+
from orix.crystal_map import Phase
48+
from orix.quaternion import Rotation
49+
from diffsims.generators.simulation_generator import SimulationGenerator
50+
51+
latt = Lattice(4, 4, 4, 90, 90, 90)
52+
atoms = [
53+
Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
54+
Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
55+
Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
56+
Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
57+
]
58+
structure_matrix = Structure(atoms=atoms, lattice=latt)
59+
p = Phase("Al", point_group="m-3m", structure=structure_matrix)
60+
gen = SimulationGenerator(accelerating_voltage=200)
61+
rot = Rotation.from_euler([[0, 0, 0], [10.0, 0.0, 0.0]], degrees=True)
62+
sim = gen.calculate_diffraction2d(
63+
phase=p,
64+
rotation=rot,
65+
reciprocal_radius=1.6768,
66+
max_excitation_error=0.02,
67+
with_direct_beam=True,
68+
)
69+
70+
fig, axs = plt.subplots(2, 2, figsize=(10, 10))
71+
for i in range(2):
72+
diff_lib["Al"]["simulations"][i].plot(
73+
size_factor=15, show_labels=True, ax=axs[i, 0]
74+
)
75+
sim.irot[i].plot(ax=axs[i, 1], size_factor=15, show_labels=True)
76+
axs[i, 0].set_xlim(-1.5, 1.5)
77+
axs[i, 0].set_ylim(-1.5, 1.5)
78+
axs[i, 1].set_xlim(-1.5, 1.5)
79+
axs[i, 1].set_ylim(-1.5, 1.5)
80+
81+
_ = axs[0, 0].set_title("Old")
82+
_ = axs[0, 1].set_title("New")
83+
84+
# %%

0 commit comments

Comments
 (0)