Merge pull request #6 from pheuer/docs_automodapi

Setup autoapi docs, add notebook examples gallery
pheuer · Nov 24, 2024 · c1f15d2 · c1f15d2
2 parents 9fbf9e4 + f0e1d36
commit c1f15d2
Show file tree

Hide file tree

Showing 31 changed files with 968 additions and 764 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -27,3 +27,11 @@ repos:
   rev: v1.0.0
   hooks:
   - id: sphinx-lint
+
+
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.2.4
+  hooks:
+  - id: codespell
+    additional_dependencies:
+      - tomli
diff --git a/test_data/test_alphas.cpsa → data/test_alphas.cpsa b/test_data/test_alphas.cpsa → data/test_alphas.cpsa
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1,5 @@
 sphinx==7.1.2
+sphinx-autoapi==3.3.3
 sphinx-rtd-theme==1.3.0rc1
+ipykernel==6.29.5
+nbsphinx==0.9.5
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -29,11 +29,21 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "autoapi.extension",
+    "nbsphinx",
 ]
 
-
-autoapi_dirs = ["../src/cr39py"]
+# sphinx-autoapi
+autoapi_dirs = ["../../src/cr39py"]
 autoapi_type = ["python"]
+autoapi_member_order = "bysource"
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-module-summary",
+    "special-members",
+    "imported-members",
+]
 
 
 intersphinx_mapping = {

diff --git a/docs/source/core/index.rst b/docs/source/core/index.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -14,13 +14,13 @@ CR39 py is a package for analyzing CR39 particle track data.
 
    Usage <usage>
 
+   API <autoapi/index>
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Modules
 
-   Core <core/index>
-   Models <models/index>
-   Scan <scan/index>
-
 
+.. nbgallery::
+   :caption: Example Notebooks
+   :name: example-gallery
+
+
+   notebooks/applying_cuts_to_a_cpsa_file
diff --git a/docs/source/models/index.rst b/docs/source/models/index.rst
diff --git a/docs/source/models/response.rst b/docs/source/models/response.rst
diff --git a/docs/source/notebooks/applying_cuts_to_a_cpsa_file.ipynb b/docs/source/notebooks/applying_cuts_to_a_cpsa_file.ipynb
diff --git a/docs/source/scan/base_scan.rst b/docs/source/scan/base_scan.rst
diff --git a/docs/source/scan/cpsa.rst b/docs/source/scan/cpsa.rst
diff --git a/docs/source/scan/cut.rst b/docs/source/scan/cut.rst
diff --git a/docs/source/scan/index.rst b/docs/source/scan/index.rst
diff --git a/docs/source/scan/subset.rst b/docs/source/scan/subset.rst
diff --git a/examples/analyzing_sample_cpsa_file.ipynb b/examples/analyzing_sample_cpsa_file.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -43,3 +43,11 @@ tests = [
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.codespell]
+# Skip ipynb files because executed files have lots of strange symbols in them.
+skip = '*.ipynb'
+# Add false positives found by codespell to ignore-words-list
+ignore-words-list = """
+hax,
+vax"""
diff --git a/src/cr39py/__init__.py b/src/cr39py/__init__.py
@@ -1,3 +1,3 @@
-from cr39py.scan.cut import Cut
 from cr39py.scan.base_scan import Scan
+from cr39py.scan.cut import Cut
 from cr39py.scan.subset import Subset
diff --git a/src/cr39py/core/__init__.py b/src/cr39py/core/__init__.py
@@ -1,4 +1,4 @@
 """
 The `~cr39py.core` module contains basic functionality that is utilized throughout
 the rest of the package.
-"""
+"""
diff --git a/src/cr39py/core/data.py b/src/cr39py/core/data.py
@@ -0,0 +1,4 @@
+import importlib.resources
+from pathlib import Path
+
+data_dir = Path(importlib.resources.files("cr39py")).parent.parent / Path("data")
diff --git a/src/cr39py/core/exportable_class.py b/src/cr39py/core/exportable_class.py
@@ -40,7 +40,7 @@ def _write_class_to_hdf5(self, group: h5py.Group, obj):
 
         group.attrs["type"] = "ExportableClassMixin"
         # Save the module location and the name of the class
-        # which will be used to retrive it
+        # which will be used to retrieve it
         group.attrs["class_module"] = str(obj.__class__.__module__)
         group.attrs["class_name"] = str(obj.__class__.__name__)
         group.attrs["timestamp"] = datetime.datetime.now().isoformat()
@@ -60,7 +60,7 @@ def _write_hdf5_entry(self, group: h5py.Group, name: str, obj: object, attrs={})
 
             group[name].attrs["type"] = "ExportableClassMixin"
             # Save the module location and the name of the class
-            # which will be used to retrive it
+            # which will be used to retrieve it
             group[name].attrs["class_module"] = str(obj.__class__.__module__)
             group[name].attrs["class_name"] = str(obj.__class__.__name__)
 

diff --git a/src/cr39py/core/types.py b/src/cr39py/core/types.py
@@ -1,3 +1,5 @@
-import numpy as np
 from typing import Annotated, TypeVar
-TrackData = Annotated[np.ndarray, "(ntracks,6)"]
+
+import numpy as np
+
+TrackData = Annotated[np.ndarray, "(ntracks,6)"]
diff --git a/src/cr39py/models/__init__.py b/src/cr39py/models/__init__.py
@@ -1,3 +1,3 @@
 """
 The `~cr39py.models` module contains models for the response of CR39.
-"""
+"""
diff --git a/src/cr39py/models/response.py b/src/cr39py/models/response.py
@@ -34,7 +34,7 @@ class TwoParameterModel:
     a response function for protons, deuterons, tritons, and alphas.
     """
 
-    # Response coefficents for protons, deuterons, tritions, and alphas
+    # Response coefficients for protons, deuterons, tritions, and alphas
     # From Table 1 of Lahmann et al. 2020 RSI
     _data = {
         "p": {"Z": 1, "A": 1, "k": 0.7609, "n": 1.497},

diff --git a/src/cr39py/scan/__init__.py b/src/cr39py/scan/__init__.py
@@ -1,5 +1,5 @@
 """
 The `~cr39py.scan` module contains classes that represent scanned CR39 data, primarily the
 `~cr39py.scan.scan.Scan` class and the `~cr39py.scan.cut.Cut` and `~cr39py.scan.subset.Subset`
-classes that are used to select subsets of the scanned tracks to analze. 
-"""
+classes that are used to select subsets of the scanned tracks to analze.
+"""