From 3e301b4d4e81218894824a075ea26bd8c5c8486d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:08:04 +0200 Subject: [PATCH 1/6] Use numpydoc for docs formatting, enable doc nav with arrow keys MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- .gitignore | 2 ++ doc/conf.py | 5 ++--- setup.py | 1 + 3 files changed, 5 insertions(+), 3 deletions(-) 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/doc/conf.py b/doc/conf.py index fbbf5be4..106e9f18 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, } @@ -175,5 +175,4 @@ def linkcode_resolve(domain, info): "ignore_pattern": "_sgskip.py", # pattern to define which will not be executed "reference_url": {"diffsims": None}, } - autosummary_generate = True 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", From 04de779d99ee8b572a2cc221ba4e0988184f87aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:09:09 +0200 Subject: [PATCH 2/6] Minor fixes to docstring formatting to allow doc build with numpydoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- diffsims/libraries/diffraction_library.py | 2 +- diffsims/libraries/vector_library.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) 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: From 5936535bed3ec5a06dcedd29555dfa3c6563752b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:40:26 +0200 Subject: [PATCH 3/6] Modify "make clean" to remove dirs for build, examples, generated API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- doc/Makefile | 6 ++++++ 1 file changed, 6 insertions(+) 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 From 8e26b4297bb80160d170b5f8bafaea5e3366f04f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:41:15 +0200 Subject: [PATCH 4/6] Fix header level for Examples README.rst, remove "Gallery of" in title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- examples/README.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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. From 5f7ac679a380b9c56b54685a0af0b77addb354b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:42:19 +0200 Subject: [PATCH 5/6] Fix doc/index examples link and formatting, restructure slightly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- doc/index.rst | 78 ++++++++++++++++++++++------------------------ doc/user/index.rst | 9 ++---- 2 files changed, 40 insertions(+), 47 deletions(-) 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 From c6cf175f5b4f71bc7c9a095e7e04b23973b4cc86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:42:56 +0200 Subject: [PATCH 6/6] Add numpydoc config (welcome, build warnings!), fix API minigallery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- doc/_templates/custom-attribute-template.rst | 3 +++ doc/_templates/custom-class-template.rst | 9 ++++--- doc/_templates/custom-function-template.rst | 3 +++ doc/_templates/custom-method-template.rst | 3 +++ doc/_templates/custom-module-template.rst | 4 +-- doc/conf.py | 28 +++++++++++++++++++- 6 files changed, 43 insertions(+), 7 deletions(-) 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 106e9f18..76a3cd7e 100644 --- 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