DOC: update readthedocs and replace sphinx-nbexamples with nbsphinx

Author: yb6599

.readthedocs.yml

@@ -1,9 +1,15 @@
 version: 2
 
-sphinx:
-  configuration: docs/conf.py
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
 
 python:
-  version: 3.7
   install:
-    - requirements: requirements-dev.txt
+    - requirements: requirements-dev.txt
+    - method: pip
+      path: .
+
+sphinx:
+  configuration: docs/conf.py

docs/conf.py

@@ -1,5 +1,7 @@
 import importlib
+import os
 import pathlib
+import sys
 
 author = "Brian de Silva, Krithika Manohar, Emily Clark"
 project = "pysensors"  # package name
@@ -11,6 +13,7 @@
 
 module = importlib.import_module(project)
 version = release = getattr(module, "__version__")
+sys.path.insert(0, os.path.abspath("."))
 
 # The master toctree document.
 master_doc = "index"
@@ -22,7 +25,8 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
-    "sphinx_nbexamples",
+    "nbsphinx",
+    "sphinx_copy_examples",
 ]
 
 apidoc_module_dir = f"../{project}"
@@ -33,7 +37,7 @@
 autodoc_member_order = "bysource"
 autoclass_content = "init"
 
-language = None
+language = "en"
 
 here = pathlib.Path(__file__).parent
 

docs/sphinx_copy_examples.py

@@ -0,0 +1,26 @@
+import shutil
+from pathlib import Path
+
+from sphinx.application import Sphinx
+
+
+def setup(app: Sphinx):
+    """Copy notebooks and supporting files from examples/ to docs/examples/"""
+    source = Path(__file__).parent.parent / "examples"
+    target = Path(__file__).parent / "examples"
+
+    if target.exists():
+        shutil.rmtree(target)
+    target.mkdir()
+
+    for item in source.rglob("*"):
+        # Accomodates for any helper scripts and data files
+        rel_path = item.relative_to(source)
+        dest_path = target / rel_path
+
+        if item.is_dir():
+            dest_path.mkdir(parents=True, exist_ok=True)
+        else:
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(item, dest_path)
+            print(f"Copied {rel_path}")

requirements-dev.txt

@@ -12,4 +12,4 @@ sphinx >= 2
 sphinxcontrib-apidoc
 sphinx_rtd_theme
 pre-commit
-sphinx-nbexamples
+nbsphinx