From 26e2bd06561bea1e0034eec367ec632f0d8311ae Mon Sep 17 00:00:00 2001 From: Yuchen Ethan Xiao Date: Wed, 30 Jul 2025 14:13:14 -0400 Subject: [PATCH 1/2] docs: fix examples documentation --- .../examples}/QPA-Quantitative phase analysis.ipynb | 0 {examples => docs/examples}/crystal_3d_widget.ipynb | 0 {examples => docs/examples}/data/cime.dat | 0 {examples => docs/examples}/data/cime.fhz | 0 {examples => docs/examples}/data/cpd-1a.prn | 0 {examples => docs/examples}/data/pbso4-n.dat | 0 {examples => docs/examples}/data/pbso4-x.dat | 0 {examples => docs/examples}/single-crystal-data.ipynb | 0 .../examples}/structure-solution-multiprocessing.ipynb | 0 .../examples}/structure-solution-powder-cimetidine.ipynb | 0 .../examples}/structure-solution-powder-pbso4.ipynb | 0 docs/source/conf.py | 2 ++ docs/source/examples/Quantitative-phase-analysis.nblink | 2 +- docs/source/examples/crystal_3d_widget.nblink | 2 +- docs/source/examples/{index.rst => examples.rst} | 0 .../examples/structure-solution-multiprocessing.nblink | 2 +- .../examples/structure-solution-powder-cimetidine.nblink | 2 +- .../examples/structure-solution-powder-pbso4.nblink | 2 +- docs/source/index.rst | 8 ++++---- requirements/docs.txt | 2 ++ 20 files changed, 13 insertions(+), 9 deletions(-) rename {examples => docs/examples}/QPA-Quantitative phase analysis.ipynb (100%) rename {examples => docs/examples}/crystal_3d_widget.ipynb (100%) rename {examples => docs/examples}/data/cime.dat (100%) rename {examples => docs/examples}/data/cime.fhz (100%) rename {examples => docs/examples}/data/cpd-1a.prn (100%) rename {examples => docs/examples}/data/pbso4-n.dat (100%) rename {examples => docs/examples}/data/pbso4-x.dat (100%) rename {examples => docs/examples}/single-crystal-data.ipynb (100%) rename {examples => docs/examples}/structure-solution-multiprocessing.ipynb (100%) rename {examples => docs/examples}/structure-solution-powder-cimetidine.ipynb (100%) rename {examples => docs/examples}/structure-solution-powder-pbso4.ipynb (100%) rename docs/source/examples/{index.rst => examples.rst} (100%) diff --git a/examples/QPA-Quantitative phase analysis.ipynb b/docs/examples/QPA-Quantitative phase analysis.ipynb similarity index 100% rename from examples/QPA-Quantitative phase analysis.ipynb rename to docs/examples/QPA-Quantitative phase analysis.ipynb diff --git a/examples/crystal_3d_widget.ipynb b/docs/examples/crystal_3d_widget.ipynb similarity index 100% rename from examples/crystal_3d_widget.ipynb rename to docs/examples/crystal_3d_widget.ipynb diff --git a/examples/data/cime.dat b/docs/examples/data/cime.dat similarity index 100% rename from examples/data/cime.dat rename to docs/examples/data/cime.dat diff --git a/examples/data/cime.fhz b/docs/examples/data/cime.fhz similarity index 100% rename from examples/data/cime.fhz rename to docs/examples/data/cime.fhz diff --git a/examples/data/cpd-1a.prn b/docs/examples/data/cpd-1a.prn similarity index 100% rename from examples/data/cpd-1a.prn rename to docs/examples/data/cpd-1a.prn diff --git a/examples/data/pbso4-n.dat b/docs/examples/data/pbso4-n.dat similarity index 100% rename from examples/data/pbso4-n.dat rename to docs/examples/data/pbso4-n.dat diff --git a/examples/data/pbso4-x.dat b/docs/examples/data/pbso4-x.dat similarity index 100% rename from examples/data/pbso4-x.dat rename to docs/examples/data/pbso4-x.dat diff --git a/examples/single-crystal-data.ipynb b/docs/examples/single-crystal-data.ipynb similarity index 100% rename from examples/single-crystal-data.ipynb rename to docs/examples/single-crystal-data.ipynb diff --git a/examples/structure-solution-multiprocessing.ipynb b/docs/examples/structure-solution-multiprocessing.ipynb similarity index 100% rename from examples/structure-solution-multiprocessing.ipynb rename to docs/examples/structure-solution-multiprocessing.ipynb diff --git a/examples/structure-solution-powder-cimetidine.ipynb b/docs/examples/structure-solution-powder-cimetidine.ipynb similarity index 100% rename from examples/structure-solution-powder-cimetidine.ipynb rename to docs/examples/structure-solution-powder-cimetidine.ipynb diff --git a/examples/structure-solution-powder-pbso4.ipynb b/docs/examples/structure-solution-powder-pbso4.ipynb similarity index 100% rename from examples/structure-solution-powder-pbso4.ipynb rename to docs/examples/structure-solution-powder-pbso4.ipynb diff --git a/docs/source/conf.py b/docs/source/conf.py index 33cf0ab..32843b6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -50,6 +50,8 @@ "sphinx.ext.intersphinx", "sphinx_rtd_theme", "sphinx_copybutton", + "nbsphinx", + "nbsphinx_link", "m2r", ] diff --git a/docs/source/examples/Quantitative-phase-analysis.nblink b/docs/source/examples/Quantitative-phase-analysis.nblink index 769508d..69c66ab 100644 --- a/docs/source/examples/Quantitative-phase-analysis.nblink +++ b/docs/source/examples/Quantitative-phase-analysis.nblink @@ -1,3 +1,3 @@ { - "path": "../../../../examples/QPA-Quantitative phase analysis.ipynb" + "path": "../../examples/QPA-Quantitative phase analysis.ipynb" } diff --git a/docs/source/examples/crystal_3d_widget.nblink b/docs/source/examples/crystal_3d_widget.nblink index 4ed202f..d67da9c 100644 --- a/docs/source/examples/crystal_3d_widget.nblink +++ b/docs/source/examples/crystal_3d_widget.nblink @@ -1,3 +1,3 @@ { - "path": "../../../../examples/crystal_3d_widget.ipynb" + "path": "../../examples/crystal_3d_widget.ipynb" } diff --git a/docs/source/examples/index.rst b/docs/source/examples/examples.rst similarity index 100% rename from docs/source/examples/index.rst rename to docs/source/examples/examples.rst diff --git a/docs/source/examples/structure-solution-multiprocessing.nblink b/docs/source/examples/structure-solution-multiprocessing.nblink index f0189eb..d2b7ec0 100644 --- a/docs/source/examples/structure-solution-multiprocessing.nblink +++ b/docs/source/examples/structure-solution-multiprocessing.nblink @@ -1,3 +1,3 @@ { - "path": "../../../../examples/structure-solution-multiprocessing.ipynb" + "path": "../../examples/structure-solution-multiprocessing.ipynb" } diff --git a/docs/source/examples/structure-solution-powder-cimetidine.nblink b/docs/source/examples/structure-solution-powder-cimetidine.nblink index 76036ab..09b56e8 100644 --- a/docs/source/examples/structure-solution-powder-cimetidine.nblink +++ b/docs/source/examples/structure-solution-powder-cimetidine.nblink @@ -1,3 +1,3 @@ { - "path": "../../../../examples/structure-solution-powder-cimetidine.ipynb" + "path": "../../examples/structure-solution-powder-cimetidine.ipynb" } diff --git a/docs/source/examples/structure-solution-powder-pbso4.nblink b/docs/source/examples/structure-solution-powder-pbso4.nblink index 052d0e2..668f722 100644 --- a/docs/source/examples/structure-solution-powder-pbso4.nblink +++ b/docs/source/examples/structure-solution-powder-pbso4.nblink @@ -1,3 +1,3 @@ { - "path": "../../../../examples/structure-solution-powder-pbso4.ipynb" + "path": "../../examples/structure-solution-powder-pbso4.ipynb" } diff --git a/docs/source/index.rst b/docs/source/index.rst index 4f93434..7f06ce2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -32,7 +32,7 @@ was developed by V. Favre-Nicolin as part of the development of the Further developments including the ability to index and refine powder patterns, solve and display crystal structures, using the global optimisation and least squares algorithms (see the -:doc:`examples/index`) are provided by Vincent Favre-Nicolin (ESRF). +:doc:`examples/examples`) are provided by Vincent Favre-Nicolin (ESRF). For a complete list of contributors, see https://github.com/diffpy/pyobjcryst/graphs/contributors and @@ -63,7 +63,7 @@ Usage & notebooks * etc.. The functionality is similar to what is available in `Fox `_. - See the :doc:`examples/index`: + See the :doc:`examples/examples`: * :doc:`3D Crystal structure display ` * :doc:`Solving the cimetidine structure from its powder pattern ` @@ -71,7 +71,7 @@ Usage & notebooks * :doc:`Meta-structure solution using multi-processing ` * :doc:`Quantitative phase analysis (QPA) ` -The **API documentation** can be found in :doc:`api/modules`. +The **API documentation** can be found in :doc:`api/pyobjcryst`. You can also read the `documentation of the underlying ObjCryst++ library `_. @@ -89,11 +89,11 @@ Table of contents :maxdepth: 2 getting-started + Examples Package API release license -======= Indices ======= diff --git a/requirements/docs.txt b/requirements/docs.txt index 5f34c6e..9c71ad2 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,5 +1,7 @@ sphinx sphinx_rtd_theme sphinx-copybutton +nbsphinx +nbsphinx-link doctr m2r From c9a4d39f3eecfa8e540b0b3513aefc45843e8cfa Mon Sep 17 00:00:00 2001 From: Yuchen Ethan Xiao Date: Wed, 30 Jul 2025 14:14:07 -0400 Subject: [PATCH 2/2] docs: add submodules in `api/pyobjcryst.rst` --- .../source/api/pyobjcryst.example_package.rst | 31 --- docs/source/api/pyobjcryst.rst | 203 +++++++++++++++++- 2 files changed, 194 insertions(+), 40 deletions(-) delete mode 100644 docs/source/api/pyobjcryst.example_package.rst diff --git a/docs/source/api/pyobjcryst.example_package.rst b/docs/source/api/pyobjcryst.example_package.rst deleted file mode 100644 index 42aec1e..0000000 --- a/docs/source/api/pyobjcryst.example_package.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _example_package documentation: - -|title| -======= - -.. |title| replace:: pyobjcryst.example_package package - -.. automodule:: pyobjcryst.example_package - :members: - :undoc-members: - :show-inheritance: - -|foo| ------ - -.. |foo| replace:: pyobjcryst.example_package.foo module - -.. automodule:: pyobjcryst.example_package.foo - :members: - :undoc-members: - :show-inheritance: - -|bar| ------ - -.. |bar| replace:: pyobjcryst.example_package.bar module - -.. automodule:: pyobjcryst.example_package.foo - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyobjcryst.rst b/docs/source/api/pyobjcryst.rst index 5df574c..80bad31 100644 --- a/docs/source/api/pyobjcryst.rst +++ b/docs/source/api/pyobjcryst.rst @@ -10,21 +10,206 @@ :undoc-members: :show-inheritance: -Subpackages ------------ - -.. toctree:: - pyobjcryst.example_package Submodules ---------- -|module| --------- +pyobjcryst.atom module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.atom + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.crystal module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.crystal + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.diffractiondatasinglecrystal module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.diffractiondatasinglecrystal + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.fourier module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.fourier + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.general module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.general + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.globaloptim module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.globaloptim + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.globals module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.globals + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.indexing module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.indexing + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.io module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.io + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.lsq module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.lsq + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.molecule module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.molecule + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.polyhedron module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.polyhedron + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.powderpattern module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.powderpattern + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.pyobjcryst_app module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.pyobjcryst_app + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.radiation module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.radiation + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.refineableobj module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.refineableobj + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.scatterer module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.scatterer + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.scatteringdata module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.scatteringdata + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.scatteringpower module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.scatteringpower + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.scatteringpowersphere module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.scatteringpowersphere + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.spacegroup module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.spacegroup + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.unitcell module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.unitcell + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.utils module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.utils + :members: + :undoc-members: + :show-inheritance: + +pyobjcryst.version module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: pyobjcryst.version + :members: + :undoc-members: + :show-inheritance: -.. |module| replace:: pyobjcryst.example_submodule module +pyobjcryst.zscatterer module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: pyobjcryst.example_submodule +.. automodule:: pyobjcryst.zscatterer :members: :undoc-members: :show-inheritance: