Sphinx: Make .pyi files available

.gitignore

@@ -28,6 +28,7 @@ docs/impactx-doxygen-web.tag.xml
 docs/openpmd-api-doxygen-web.tag.xml
 docs/doxyhtml/
 docs/doxyxml/
+docs/source/amrex.zip
 docs/source/_static/
 
 ####################

docs/conda.yml

@@ -7,6 +7,7 @@ channels:
 dependencies:
   - python
   - doxygen
+  - numpy
   - pip
   - pip:
     - -r requirements.txt

docs/source/conf.py

@@ -26,6 +26,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import shutil
 import subprocess
 import sys
 import urllib.request
@@ -236,3 +237,35 @@ def download_with_headers(url, filename):
     "cp impactx-doxygen-web.tag.xml source/_static/doxyhtml/",
     shell=True,
 )
+
+# Copy .pyi interface files and make them available as .py files
+# path to .pyi files w/o having them installed
+src_path = "../../src/python/impactx"
+api_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "_static/pyapi")
+dst_path = os.path.join(api_path, "impactx")
+if os.path.exists(dst_path) and os.path.isdir(dst_path):
+    shutil.rmtree(dst_path)
+shutil.copytree(src_path, dst_path)
+
+for subdir, _dirs, files in os.walk(dst_path):
+    for f in files:
+        if f.find(".pyi") > 0:
+            dir_path = os.path.relpath(subdir, dst_path)
+            old_path = os.path.join(dir_path, f)
+            new_path = old_path.replace(".pyi", ".py")
+            os.replace(
+                os.path.join(dst_path, old_path), os.path.join(dst_path, new_path)
+            )
+
+# insert into PYTHONPATH
+sys.path.insert(0, os.path.join(dst_path, ".."))
+
+# make archive for download of dependent Sphinx projects
+shutil.make_archive(dst_path, "zip", dst_path)
+
+# Download pyAMReX stub files
+download_with_headers(
+    url="https://pyamrex.readthedocs.io/en/latest/_static/pyapi/amrex.zip",
+    filename="amrex.zip",
+)
+shutil.unpack_archive("amrex.zip", os.path.join(api_path, "amrex"))

docs/source/usage/python.rst

@@ -76,7 +76,7 @@ Collective Effects & Overall Simulation Parameters
 
         When running in envelope mode (when ``algo.track = "envelope"``), this model currently assumes that ``<xy> = <yt> = <tx> = 0``.
 
-      * ``"Gauss3D"`: Calculate 3D space charge forces as if the beam was a Gaussian distribution.
+      * ``"Gauss3D"``: Calculate 3D space charge forces as if the beam was a Gaussian distribution.
 
         This model is supported only in particle tracking mode (when ``algo.track = "particles"``).
         Ref.: J. Qiang et al., "Two-and-a-half dimensional symplectic space-charge solver", LBNL Report Number: LBNL-2001674 (2025).

src/python/impactx/MADXParser.py

@@ -14,11 +14,7 @@
 import warnings
 
 
-class MADXParserError(Exception):
-    pass
-
-
-class MADXInputError(MADXParserError):
+class MADXInputError(Exception):
     def __init__(self, args, with_traceback):
         self.args = args
         self.with_traceback = with_traceback