diff --git a/.gitignore b/.gitignore index 643427c0..c4531a41 100644 --- 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 index b0c084e1..ba222156 100644 --- 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 index f56860cd..35e5a096 100644 --- 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 index ed880990..b687a144 100644 --- 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 index c31bebe0..ea206ece 100644 --- 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 index 8ada3fb0..8ea2b40f 100644 --- 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 index 5ffed09e..b109cab9 100644 --- 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 }}`` \ No newline at end of file diff --git a/doc/_templates/custom-method-template.rst b/doc/_templates/custom-method-template.rst index 306d2aab..3ebddf87 100644 --- 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 }}`` \ No newline at end of file diff --git a/doc/_templates/custom-module-template.rst b/doc/_templates/custom-module-template.rst index 05d36cd7..f45d4f56 100644 --- 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 index fbbf5be4..76a3cd7e 100644 --- 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 index 676e746b..a77c1dcb 100644 --- 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 - -.. 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 `__ or Further details are available in the :doc:`installation guide `. + 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 index ec4afb3f..f976ea83 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -2,9 +2,6 @@ User guide ========== -See the `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 ../examples/index.rst - installation.rst .. toctree:: :caption: Resources diff --git a/examples/README.rst b/examples/README.rst index baa7152e..0e9e731a 100644 --- 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 index b008f375..6d835883 100644 --- 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",