From 145f7f7fda329f9809af4b8efcba79d599db953c Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Mon, 4 Aug 2025 15:51:08 -0400 Subject: [PATCH 1/4] style: use pydata sphinx theme to render the docs --- docs/source/conf.py | 25 +++++++++++++++++++++---- requirements/docs.txt | 2 +- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 32843b6..3f9fa5c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,11 +48,10 @@ "sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", - "sphinx_rtd_theme", "sphinx_copybutton", "nbsphinx", "nbsphinx_link", - "m2r", + "m2r2", ] # Add any paths that contain templates here, relative to this directory. @@ -134,7 +133,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" +html_theme = "pydata_sphinx_theme" html_context = { "display_github": True, @@ -149,7 +148,25 @@ # documentation. # html_theme_options = { - "navigation_with_keys": "true", + "show_nav_level": 2, + "navigation_depth": 2, + "navbar_align": "left", + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/diffpy/pyobjcryst", + "icon": "fab-brands fa-github", + }, + ], + # "primary_sidebar_end": ["indices.html", "sidebar-ethical-ads.html"] +} + +# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars +html_sidebars = { + "**": ["globaltoc.html", "sidebar-nav-bs"], + # "**": ["localtoc.html"], + # "**": ["sidebar-nav-bs"], + # "": ["index", "manual-intro", "tutorials", "manual"] } # Add any paths that contain custom themes here, relative to this directory. diff --git a/requirements/docs.txt b/requirements/docs.txt index 9c71ad2..8656526 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,5 +1,5 @@ sphinx -sphinx_rtd_theme +pydata-sphinx-theme sphinx-copybutton nbsphinx nbsphinx-link From 7c7495df29981bb5553e95069303619a9ca57910 Mon Sep 17 00:00:00 2001 From: Yuchen Ethan Xiao Date: Mon, 4 Aug 2025 17:00:33 -0400 Subject: [PATCH 2/4] fix: remove nbsphinx_link dependency --- docs/source/conf.py | 15 ++++++++++++--- .../examples/Quantitative-phase-analysis.nblink | 3 --- docs/source/examples/crystal_3d_widget.nblink | 3 --- docs/source/examples/examples.rst | 11 +++++------ .../structure-solution-multiprocessing.nblink | 3 --- .../structure-solution-powder-cimetidine.nblink | 3 --- .../structure-solution-powder-pbso4.nblink | 3 --- requirements/docs.txt | 2 +- 8 files changed, 18 insertions(+), 25 deletions(-) delete mode 100644 docs/source/examples/Quantitative-phase-analysis.nblink delete mode 100644 docs/source/examples/crystal_3d_widget.nblink delete mode 100644 docs/source/examples/structure-solution-multiprocessing.nblink delete mode 100644 docs/source/examples/structure-solution-powder-cimetidine.nblink delete mode 100644 docs/source/examples/structure-solution-powder-pbso4.nblink diff --git a/docs/source/conf.py b/docs/source/conf.py index 3f9fa5c..3fa0cd0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,6 +17,7 @@ import time from importlib.metadata import version from pathlib import Path +import shutil # Attempt to import the version dynamically from GitHub tag. try: @@ -34,6 +35,15 @@ # abbreviations ab_authors = "Billinge Group members" +# Include notebooks at build time. +root_dir = Path(__file__).resolve().parents[1] +external_nb_dir = root_dir / 'examples' +for f in external_nb_dir.glob("*.ipynb"): + dest = Path(__file__).parent / 'examples' / f.name + if dest.exists(): + dest.unlink() + shutil.copy(f, dest) + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -50,8 +60,7 @@ "sphinx.ext.intersphinx", "sphinx_copybutton", "nbsphinx", - "nbsphinx_link", - "m2r2", + "m2r", ] # Add any paths that contain templates here, relative to this directory. @@ -63,7 +72,7 @@ source_suffix = [".rst", ".md"] # The encoding of source files. -# source_encoding = 'utf-8-sig' +# source_encoding = eutf-8-sig' # The master toctree document. master_doc = "index" diff --git a/docs/source/examples/Quantitative-phase-analysis.nblink b/docs/source/examples/Quantitative-phase-analysis.nblink deleted file mode 100644 index 69c66ab..0000000 --- a/docs/source/examples/Quantitative-phase-analysis.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "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 deleted file mode 100644 index d67da9c..0000000 --- a/docs/source/examples/crystal_3d_widget.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "path": "../../examples/crystal_3d_widget.ipynb" -} diff --git a/docs/source/examples/examples.rst b/docs/source/examples/examples.rst index 46a3d89..b5e0658 100644 --- a/docs/source/examples/examples.rst +++ b/docs/source/examples/examples.rst @@ -4,9 +4,8 @@ Example notebooks Several examples available in the pyobjcryst repository: - :doc:`3D Crystal structure display ` -======================================================= +================================================================ Example of importing a CIF file from a file or the `Crystallography Open Database `_ @@ -14,7 +13,7 @@ and displaying it in a widget using `3dmol.js `_. :doc:`Solving the cimetidine structure from its powder pattern ` -====================================================================================================== +=============================================================================================================== In this example, a powder pattern is used to solve the crystal structure of Cimetidine. This covers all the steps: loading the @@ -23,7 +22,7 @@ the spacegroup, profile fitting, and solving the structure using a global optimisation algorithm. :doc:`Solving the PbSO4 structure from its X and N powder patterns ` -===================================================================================================== +============================================================================================================== In this example, two powder patterns (X-ray and neutron) are used to solve the crystal structure of PbSO4. This covers all the steps: loading the @@ -32,14 +31,14 @@ the spacegroup, profile fitting for the two patterns, and solving the structure using a global optimisation algorithm. :doc:`Meta-structure solution using multi-processing ` -========================================================================================== +=================================================================================================== This is a more advanced example where 8 different spacegroups are tested in parallel to determine which one is correct. The solutions can then be compared and displayed individually. :doc:`Quantitative phase analysis (QPA) ` -====================================================================== +=============================================================================== Example of QPA based on the data available from the `1999 Round Robin `_, diff --git a/docs/source/examples/structure-solution-multiprocessing.nblink b/docs/source/examples/structure-solution-multiprocessing.nblink deleted file mode 100644 index d2b7ec0..0000000 --- a/docs/source/examples/structure-solution-multiprocessing.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "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 deleted file mode 100644 index 09b56e8..0000000 --- a/docs/source/examples/structure-solution-powder-cimetidine.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "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 deleted file mode 100644 index 668f722..0000000 --- a/docs/source/examples/structure-solution-powder-pbso4.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "path": "../../examples/structure-solution-powder-pbso4.ipynb" -} diff --git a/requirements/docs.txt b/requirements/docs.txt index 8656526..2a1b3f9 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -2,6 +2,6 @@ sphinx pydata-sphinx-theme sphinx-copybutton nbsphinx -nbsphinx-link doctr m2r +ipykernel From 67bcd5450defad4a842aa3da46c433bcf9a6b4c9 Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Mon, 4 Aug 2025 18:20:39 -0400 Subject: [PATCH 3/4] chore: add lxml-html-clean as a dependency to requirements folder, fix github icon link in pydata theme --- docs/source/conf.py | 8 ++++---- requirements/docs.txt | 1 + 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3fa0cd0..a515685 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,11 +13,11 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import shutil import sys import time from importlib.metadata import version from pathlib import Path -import shutil # Attempt to import the version dynamically from GitHub tag. try: @@ -37,9 +37,9 @@ # Include notebooks at build time. root_dir = Path(__file__).resolve().parents[1] -external_nb_dir = root_dir / 'examples' +external_nb_dir = root_dir / "examples" for f in external_nb_dir.glob("*.ipynb"): - dest = Path(__file__).parent / 'examples' / f.name + dest = Path(__file__).parent / "examples" / f.name if dest.exists(): dest.unlink() shutil.copy(f, dest) @@ -164,7 +164,7 @@ { "name": "GitHub", "url": "https://github.com/diffpy/pyobjcryst", - "icon": "fab-brands fa-github", + "icon": "fab fa-github", }, ], # "primary_sidebar_end": ["indices.html", "sidebar-ethical-ads.html"] diff --git a/requirements/docs.txt b/requirements/docs.txt index 2a1b3f9..4cb02b0 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -5,3 +5,4 @@ nbsphinx doctr m2r ipykernel +lxml-html-clean From e5acfbd2e207fdbe287b0bac798cb24c6143e404 Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Tue, 5 Aug 2025 02:20:02 -0400 Subject: [PATCH 4/4] chore: perform minor fixes according to feedback --- docs/source/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a515685..1570b0f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -72,7 +72,7 @@ source_suffix = [".rst", ".md"] # The encoding of source files. -# source_encoding = eutf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. master_doc = "index" @@ -142,6 +142,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # +# html_theme = "sphinx_rtd_theme" html_theme = "pydata_sphinx_theme" html_context = {