chore: remove nbsphinx link and use the pydata theme to render our documentation

docs/source/conf.py

@@ -13,6 +13,7 @@
 # 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
@@ -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.
@@ -48,10 +58,8 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
-    "sphinx_rtd_theme",
     "sphinx_copybutton",
     "nbsphinx",
-    "nbsphinx_link",
     "m2r",
 ]
 
@@ -134,7 +142,8 @@
 # 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 = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
 
 html_context = {
     "display_github": True,
@@ -149,7 +158,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 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"],
+    # "<page_pattern>": ["index", "manual-intro", "tutorials", "manual"]
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

docs/source/examples/examples.rst

@@ -4,17 +4,16 @@ Example notebooks
 
 Several examples available in the pyobjcryst repository:
 
-
 :doc:`3D Crystal structure display <crystal_3d_widget>`
-=======================================================
+================================================================
 
 Example of importing a CIF file from a file or the
 `Crystallography Open Database <http://crystallography.net/cod/>`_
 and displaying it in a widget using
 `3dmol.js <https://3dmol.csb.pitt.edu/>`_.
 
 :doc:`Solving the cimetidine structure from its powder pattern <structure-solution-powder-cimetidine>`
-======================================================================================================
+===============================================================================================================
 
 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 <structure-solution-powder-pbso4>`
-=====================================================================================================
+==============================================================================================================
 
 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 <structure-solution-multiprocessing>`
-==========================================================================================
+===================================================================================================
 
 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) <Quantitative-phase-analysis>`
-======================================================================
+===============================================================================
 
 Example of QPA based on the data available from the `1999 Round Robin
 <https://www.iucr.org/__data/iucr/powder/QARR/samples.htm>`_,

requirements/docs.txt

@@ -1,7 +1,8 @@
 sphinx
-sphinx_rtd_theme
+pydata-sphinx-theme
 sphinx-copybutton
 nbsphinx
-nbsphinx-link
 doctr
 m2r
+ipykernel
+lxml-html-clean