Merge pull request #26 from dynamicslab/docs-example-nb-fix

ReadTheDocs Fix

Author: kmanohar

.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

README.rst

@@ -306,8 +306,8 @@ References
    (2024): 15501 - 15516.
    `[DOI] <https://doi.org/10.1109/JSEN.2024.3368875>`__
 
-.. |Build| image:: https://github.com/dynamicslab/pysensors/workflows/Tests/badge.svg
-    :target: https://github.com/dynamicslab/pysensors/actions?query=workflow%3ATests
+.. |Build| image:: https://github.com/dynamicslab/pysensors/workflows/main.yml/badge.svg
+    :target: https://github.com/dynamicslab/pysensors/actions?query=workflow%3ACI
 
 .. |RTD| image:: https://readthedocs.org/projects/python-sensors/badge/?version=latest
     :target: https://python-sensors.readthedocs.io/en/latest/?badge=latest

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}")

examples/functional_constraints_class.ipynb

@@ -148,7 +148,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Unconstrained sensor placaement:\n"
+    "### Unconstrained sensor placement:\n"
    ]
   },
   {
@@ -565,7 +565,7 @@
    "source": [
     "### Functional constaints:\n",
     "\n",
-    "Suppose the user wants to constrain a circular aea centered at x = 20, y = 30 with a radius (r = 5)"
+    "Suppose the user wants to constrain a circular aea centered at $x = 20$, $y = 30$ with a radius ($r = 5$)"
    ]
   },
   {
@@ -862,7 +862,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### We want to constrain the region beyond x = 10 and x = 20 and y = 0 and y = 64"
+    "### We want to constrain the region beyond $x = 10$ and $x = 20$ and $y = 0$ and $y = 64$"
    ]
   },
   {
@@ -2155,7 +2155,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Now let us consider an example where the user inputs the equation that they are considering as a constraint in a string of the form (x-30)^2 + (y-40)^2 < 25"
+    "### Now let us consider an example where the user inputs the equation that they are considering as a constraint in a string of the form $(x-30)^2 + (y-40)^2 < 25$"
    ]
   },
   {
@@ -2379,7 +2379,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "base",
+   "display_name": "venv",
    "language": "python",
    "name": "python3"
   },
@@ -2393,7 +2393,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

examples/index.rst

@@ -0,0 +1,17 @@
+PySensors Examples
+==================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Example Notebooks
+
+   pysensors_overview
+   basis_comparison
+   classification
+   cost_constrained_qr
+   cross_validation
+   sea_surface_temperature
+   vandermonde
+   spatially_constrained_qr
+   functional_constraints_class
+   simulation_constrained_sensing

examples/simulation_constrained_sensing.ipynb

@@ -624,7 +624,7 @@
    "source": [
     "### Functional constraints:\n",
     "\n",
-    "Suppose the user wants to constrain a circular area centered at x = 0.025 m, y = 0 m with a radius (r = 0.02 m).\n",
+    "Suppose the user wants to constrain a circular area centered at $x = 0.025$ m, $y = 0$ m with a radius ($r = 0.02$ m).\n",
     "The user can do see by initiating an instance of the class Circle which has functionalities such as :\n",
     "- Plotting\n",
     "- Plotting all possible sensor locations\n",
@@ -928,9 +928,9 @@
    "source": [
     "### Trying out a custom parabolic constraint: ( Now what if the user has provided a python file with the required constraints)\n",
     "\n",
-    "##### Here the parabola is centered at (h,k) = (0.025,0.00)\n",
-    "##### The equation used is $y = a(x-h)^2 -k$ where a = 100\n",
-    "##### A line drawn at y = 0.2 closes the parabola and the constrained region is bound by the parabola and the line."
+    "##### Here the parabola is centered at $(h,k) = (0.025,0.00)$\n",
+    "##### The equation used is $y = a(x-h)^2 -k$ where $a = 100$\n",
+    "##### A line drawn at $y = 0.2$ closes the parabola and the constrained region is bound by the parabola and the line."
    ]
   },
   {
@@ -1548,7 +1548,7 @@
    "metadata": {},
    "source": [
     "For example the equation of a parabola is :\n",
-    "a(x-h)^2 - (y- k)"
+    "$a(x-h)^2 - (y- k)$"
    ]
   },
   {
@@ -1799,7 +1799,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "base",
+   "display_name": "venv",
    "language": "python",
    "name": "python3"
   },
@@ -1813,7 +1813,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.12.3"
   },
   "orig_nbformat": 4
  },

examples/spatially_constrained_qr.ipynb

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