From 81da3eea03ca69b7eae439d6ed2e7ee41605af39 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 15 Dec 2025 20:08:31 -0500 Subject: [PATCH 01/23] init sphinx --- .gitignore | 1 + doc/Makefile | 20 ++++++++++++++++++++ doc/make.bat | 35 +++++++++++++++++++++++++++++++++++ doc/placeholder | 0 doc/source/conf.py | 28 ++++++++++++++++++++++++++++ doc/source/index.rst | 17 +++++++++++++++++ 6 files changed, 101 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/make.bat delete mode 100644 doc/placeholder create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/.gitignore b/.gitignore index 47650c0e..44b61695 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ PyORBIT.egg-info *.so .*.swp .eggs +.venv diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/placeholder b/doc/placeholder deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..83bb65fd --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'PyORBIT3' +copyright = '2025, PyORBIT Collaboration' +author = 'PyORBIT Collaboration' +release = 'v3.0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..dfd70787 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,17 @@ +.. PyORBIT3 documentation master file, created by + sphinx-quickstart on Mon Dec 15 20:07:23 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +PyORBIT3 documentation +====================== + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + From 67f353f5aab45f1fa7a18f6066bbe9a2507d0741 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 15 Dec 2025 20:19:03 -0500 Subject: [PATCH 02/23] sphinx-apidoc first pass --- doc/source/conf.py | 18 +++-- doc/source/index.rst | 41 +++++++++++- doc/source/modules/orbit.aperture.rst | 31 +++++++++ doc/source/modules/orbit.bumps.rst | 31 +++++++++ doc/source/modules/orbit.bunch_generators.rst | 19 ++++++ doc/source/modules/orbit.bunch_utils.rst | 25 +++++++ doc/source/modules/orbit.collimation.rst | 25 +++++++ doc/source/modules/orbit.core.rst | 10 +++ doc/source/modules/orbit.diagnostics.rst | 37 +++++++++++ doc/source/modules/orbit.errors.rst | 25 +++++++ doc/source/modules/orbit.fieldtracker.rst | 25 +++++++ doc/source/modules/orbit.foils.rst | 25 +++++++ doc/source/modules/orbit.impedances.rst | 25 +++++++ doc/source/modules/orbit.injection.rst | 43 ++++++++++++ doc/source/modules/orbit.kickernodes.rst | 37 +++++++++++ doc/source/modules/orbit.lattice.rst | 37 +++++++++++ doc/source/modules/orbit.matching.rst | 19 ++++++ doc/source/modules/orbit.matrix_lattice.rst | 25 +++++++ doc/source/modules/orbit.orbit_correction.rst | 19 ++++++ doc/source/modules/orbit.parsers.rst | 37 +++++++++++ doc/source/modules/orbit.py_linac.errors.rst | 19 ++++++ doc/source/modules/orbit.py_linac.lattice.rst | 61 +++++++++++++++++ .../orbit.py_linac.lattice_modifications.rst | 49 ++++++++++++++ .../modules/orbit.py_linac.linac_parsers.rst | 25 +++++++ .../modules/orbit.py_linac.materials.rst | 19 ++++++ .../orbit.py_linac.orbit_correction.rst | 19 ++++++ .../orbit.py_linac.overlapping_fields.rst | 31 +++++++++ .../orbit.py_linac.rf_field_readers.rst | 25 +++++++ doc/source/modules/orbit.py_linac.rst | 25 +++++++ doc/source/modules/orbit.rf_cavities.rst | 25 +++++++ doc/source/modules/orbit.rst | 42 ++++++++++++ .../orbit.space_charge.directforce2p5d.rst | 25 +++++++ doc/source/modules/orbit.space_charge.rst | 43 ++++++++++++ .../modules/orbit.space_charge.sc1d.rst | 25 +++++++ .../orbit.space_charge.sc2dslicebyslice.rst | 25 +++++++ .../modules/orbit.space_charge.sc2p5d.rst | 25 +++++++ .../modules/orbit.space_charge.sc3d.rst | 25 +++++++ doc/source/modules/orbit.teapot.rst | 25 +++++++ doc/source/modules/orbit.teapot_base.rst | 10 +++ doc/source/modules/orbit.time_dep.rst | 25 +++++++ doc/source/modules/orbit.utils.fitting.rst | 49 ++++++++++++++ .../modules/orbit.utils.orbit_mpi_utils.rst | 37 +++++++++++ doc/source/modules/orbit.utils.rst | 65 +++++++++++++++++++ doc/source/modules/orbit.utils.xml.rst | 19 ++++++ 44 files changed, 1287 insertions(+), 5 deletions(-) create mode 100644 doc/source/modules/orbit.aperture.rst create mode 100644 doc/source/modules/orbit.bumps.rst create mode 100644 doc/source/modules/orbit.bunch_generators.rst create mode 100644 doc/source/modules/orbit.bunch_utils.rst create mode 100644 doc/source/modules/orbit.collimation.rst create mode 100644 doc/source/modules/orbit.core.rst create mode 100644 doc/source/modules/orbit.diagnostics.rst create mode 100644 doc/source/modules/orbit.errors.rst create mode 100644 doc/source/modules/orbit.fieldtracker.rst create mode 100644 doc/source/modules/orbit.foils.rst create mode 100644 doc/source/modules/orbit.impedances.rst create mode 100644 doc/source/modules/orbit.injection.rst create mode 100644 doc/source/modules/orbit.kickernodes.rst create mode 100644 doc/source/modules/orbit.lattice.rst create mode 100644 doc/source/modules/orbit.matching.rst create mode 100644 doc/source/modules/orbit.matrix_lattice.rst create mode 100644 doc/source/modules/orbit.orbit_correction.rst create mode 100644 doc/source/modules/orbit.parsers.rst create mode 100644 doc/source/modules/orbit.py_linac.errors.rst create mode 100644 doc/source/modules/orbit.py_linac.lattice.rst create mode 100644 doc/source/modules/orbit.py_linac.lattice_modifications.rst create mode 100644 doc/source/modules/orbit.py_linac.linac_parsers.rst create mode 100644 doc/source/modules/orbit.py_linac.materials.rst create mode 100644 doc/source/modules/orbit.py_linac.orbit_correction.rst create mode 100644 doc/source/modules/orbit.py_linac.overlapping_fields.rst create mode 100644 doc/source/modules/orbit.py_linac.rf_field_readers.rst create mode 100644 doc/source/modules/orbit.py_linac.rst create mode 100644 doc/source/modules/orbit.rf_cavities.rst create mode 100644 doc/source/modules/orbit.rst create mode 100644 doc/source/modules/orbit.space_charge.directforce2p5d.rst create mode 100644 doc/source/modules/orbit.space_charge.rst create mode 100644 doc/source/modules/orbit.space_charge.sc1d.rst create mode 100644 doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst create mode 100644 doc/source/modules/orbit.space_charge.sc2p5d.rst create mode 100644 doc/source/modules/orbit.space_charge.sc3d.rst create mode 100644 doc/source/modules/orbit.teapot.rst create mode 100644 doc/source/modules/orbit.teapot_base.rst create mode 100644 doc/source/modules/orbit.time_dep.rst create mode 100644 doc/source/modules/orbit.utils.fitting.rst create mode 100644 doc/source/modules/orbit.utils.orbit_mpi_utils.rst create mode 100644 doc/source/modules/orbit.utils.rst create mode 100644 doc/source/modules/orbit.utils.xml.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 83bb65fd..12246764 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,6 +3,12 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +# -- Path setup -------------------------------------------------------------- +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -14,15 +20,19 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] +autosummary_generate = True +napoleon_numpy_docstring = True templates_path = ['_templates'] exclude_patterns = [] - - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' +html_theme = 'furo' html_static_path = ['_static'] +html_show_source_link = True +html_theme_options = { + # 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', +} diff --git a/doc/source/index.rst b/doc/source/index.rst index dfd70787..d16735f7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,5 +13,44 @@ documentation for details. .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Modules + :hidden: + modules/orbit.aperture + modules/orbit.bump + modules/orbit.bunch_generators + modules/orbit.bunch_utils + modules/orbit.collimation + modules/orbit.diagnostics + modules/orbit.errors + modules/orbit.fieldtracker + modules/orbit.foils + modules/orbit.impedances + modules/orbit.injection + modules/orbit.kickernodes + modules/orbit.lattice + modules/orbit.matching + modules/orbit.matrix_lattice + modules/orbit.orbit_correction + modules/orbit.parsers + modules/orbit.py_linac.errors + modules/orbit.py_linac.lattice + modules/orbit.py_linac.lattice_modifications + modules/orbit.py_linac.linac_parsers + modules/orbit.py_linac.materials + modules/orbit.py_linac.orbit_correction + modules/orbit.py_linac.overlapping_fields + modules/orbit.py_linac.rf_field_readers + modules/orbit.py_linac + modules/orbit.rf_cavities + modules/orbit.space_charge.directforce2p5d + modules/orbit.space_charge + modules/orbit.space_charge.sc1d + modules/orbit.space_charge.sc2dslicebyslice + modules/orbit.space_charge.sc2p5d + modules/orbit.space_charge.sc3d + modules/orbit.teapot + modules/orbit.teapot_base + modules/orbit.time_dep + modules/orbit.utils.fitting + modules/orbit.utils.orbit_mpi_utils diff --git a/doc/source/modules/orbit.aperture.rst b/doc/source/modules/orbit.aperture.rst new file mode 100644 index 00000000..9cf8d713 --- /dev/null +++ b/doc/source/modules/orbit.aperture.rst @@ -0,0 +1,31 @@ +orbit.aperture package +====================== + +Submodules +---------- + + +.. automodule:: orbit.aperture.ApertureLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.aperture.ApertureLatticeRangeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.aperture.TeapotApertureNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.aperture + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bumps.rst b/doc/source/modules/orbit.bumps.rst new file mode 100644 index 00000000..639b975e --- /dev/null +++ b/doc/source/modules/orbit.bumps.rst @@ -0,0 +1,31 @@ +orbit.bumps package +=================== + +Submodules +---------- + + +.. automodule:: orbit.bumps.BumpLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bumps.TeapotBumpNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bumps.bumps + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bumps + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bunch_generators.rst b/doc/source/modules/orbit.bunch_generators.rst new file mode 100644 index 00000000..d2aae682 --- /dev/null +++ b/doc/source/modules/orbit.bunch_generators.rst @@ -0,0 +1,19 @@ +orbit.bunch\_generators package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.bunch_generators.distribution_generators + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bunch_generators + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bunch_utils.rst b/doc/source/modules/orbit.bunch_utils.rst new file mode 100644 index 00000000..35d80b35 --- /dev/null +++ b/doc/source/modules/orbit.bunch_utils.rst @@ -0,0 +1,25 @@ +orbit.bunch\_utils package +========================== + +Submodules +---------- + + +.. automodule:: orbit.bunch_utils.particleidnumber + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bunch_utils.serialize + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bunch_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.collimation.rst b/doc/source/modules/orbit.collimation.rst new file mode 100644 index 00000000..b6100fdb --- /dev/null +++ b/doc/source/modules/orbit.collimation.rst @@ -0,0 +1,25 @@ +orbit.collimation package +========================= + +Submodules +---------- + + +.. automodule:: orbit.collimation.TeapotCollimatorNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.collimation.collimationLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.collimation + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.core.rst b/doc/source/modules/orbit.core.rst new file mode 100644 index 00000000..53921b7d --- /dev/null +++ b/doc/source/modules/orbit.core.rst @@ -0,0 +1,10 @@ +orbit.core package +================== + +Module contents +--------------- + +.. automodule:: orbit.core + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.diagnostics.rst b/doc/source/modules/orbit.diagnostics.rst new file mode 100644 index 00000000..454b5406 --- /dev/null +++ b/doc/source/modules/orbit.diagnostics.rst @@ -0,0 +1,37 @@ +orbit.diagnostics package +========================= + +Submodules +---------- + + +.. automodule:: orbit.diagnostics.TeapotDiagnosticsNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.diagnostics + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.diagnosticsLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.profiles + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.diagnostics + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.errors.rst b/doc/source/modules/orbit.errors.rst new file mode 100644 index 00000000..8ff1deb7 --- /dev/null +++ b/doc/source/modules/orbit.errors.rst @@ -0,0 +1,25 @@ +orbit.errors package +==================== + +Submodules +---------- + + +.. automodule:: orbit.errors.ErrorLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.errors.ErrorNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.errors + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.fieldtracker.rst b/doc/source/modules/orbit.fieldtracker.rst new file mode 100644 index 00000000..bba5190f --- /dev/null +++ b/doc/source/modules/orbit.fieldtracker.rst @@ -0,0 +1,25 @@ +orbit.fieldtracker package +========================== + +Submodules +---------- + + +.. automodule:: orbit.fieldtracker.TeapotFieldLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.fieldtracker.TeapotFieldTrackerNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.fieldtracker + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.foils.rst b/doc/source/modules/orbit.foils.rst new file mode 100644 index 00000000..6d1c11b4 --- /dev/null +++ b/doc/source/modules/orbit.foils.rst @@ -0,0 +1,25 @@ +orbit.foils package +=================== + +Submodules +---------- + + +.. automodule:: orbit.foils.TeapotFoilNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.foils.foilLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.foils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.impedances.rst b/doc/source/modules/orbit.impedances.rst new file mode 100644 index 00000000..4c540fb2 --- /dev/null +++ b/doc/source/modules/orbit.impedances.rst @@ -0,0 +1,25 @@ +orbit.impedances package +======================== + +Submodules +---------- + + +.. automodule:: orbit.impedances.ImpedanceLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.impedances.ImpedanceNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.impedances + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.injection.rst b/doc/source/modules/orbit.injection.rst new file mode 100644 index 00000000..f5b4963e --- /dev/null +++ b/doc/source/modules/orbit.injection.rst @@ -0,0 +1,43 @@ +orbit.injection package +======================= + +Submodules +---------- + + +.. automodule:: orbit.injection.InjectionLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.TeapotInjectionNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.distributions + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.injectparticles + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.joho + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.injection + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.kickernodes.rst b/doc/source/modules/orbit.kickernodes.rst new file mode 100644 index 00000000..2b000f0b --- /dev/null +++ b/doc/source/modules/orbit.kickernodes.rst @@ -0,0 +1,37 @@ +orbit.kickernodes package +========================= + +Submodules +---------- + + +.. automodule:: orbit.kickernodes.KickerLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.TeapotKickerNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.kicker + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.waveforms + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.kickernodes + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.lattice.rst b/doc/source/modules/orbit.lattice.rst new file mode 100644 index 00000000..68ed9568 --- /dev/null +++ b/doc/source/modules/orbit.lattice.rst @@ -0,0 +1,37 @@ +orbit.lattice package +===================== + +Submodules +---------- + + +.. automodule:: orbit.lattice.AccActionsContainer + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccLattice + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccNodeBunchTracker + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.matching.rst b/doc/source/modules/orbit.matching.rst new file mode 100644 index 00000000..020f4937 --- /dev/null +++ b/doc/source/modules/orbit.matching.rst @@ -0,0 +1,19 @@ +orbit.matching package +====================== + +Submodules +---------- + + +.. automodule:: orbit.matching.matching + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.matching + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.matrix_lattice.rst b/doc/source/modules/orbit.matrix_lattice.rst new file mode 100644 index 00000000..b88fc3c4 --- /dev/null +++ b/doc/source/modules/orbit.matrix_lattice.rst @@ -0,0 +1,25 @@ +orbit.matrix\_lattice package +============================= + +Submodules +---------- + + +.. automodule:: orbit.matrix_lattice.BaseMATRIX + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.matrix_lattice.MATRIX_Lattice + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.matrix_lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.orbit_correction.rst b/doc/source/modules/orbit.orbit_correction.rst new file mode 100644 index 00000000..87d458d1 --- /dev/null +++ b/doc/source/modules/orbit.orbit_correction.rst @@ -0,0 +1,19 @@ +orbit.orbit\_correction package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.orbit_correction.orbit_correction + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.orbit_correction + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.parsers.rst b/doc/source/modules/orbit.parsers.rst new file mode 100644 index 00000000..8fffb512 --- /dev/null +++ b/doc/source/modules/orbit.parsers.rst @@ -0,0 +1,37 @@ +orbit.parsers package +===================== + +Submodules +---------- + + +.. automodule:: orbit.parsers.field_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.mad_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.madx_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.sad_parser + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.parsers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.errors.rst b/doc/source/modules/orbit.py_linac.errors.rst new file mode 100644 index 00000000..304668e5 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.errors.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.errors package +============================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.errors.ErrorNodesAndControllersLib + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.errors + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice.rst b/doc/source/modules/orbit.py_linac.lattice.rst new file mode 100644 index 00000000..08f273fb --- /dev/null +++ b/doc/source/modules/orbit.py_linac.lattice.rst @@ -0,0 +1,61 @@ +orbit.py\_linac.lattice package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.lattice.LinacAccLatticeFunc + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacAccLatticeLib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacApertureNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacDiagnosticsNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacFieldOverlappingNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacRfGapNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacTransportMatrixGenNodes + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice_modifications.rst b/doc/source/modules/orbit.py_linac.lattice_modifications.rst new file mode 100644 index 00000000..a04b7547 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.lattice_modifications.rst @@ -0,0 +1,49 @@ +orbit.py\_linac.lattice\_modifications package +============================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.lattice_modifications.apertures_additions_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.errors_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.quad_overlap_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.rf_models_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.rf_quad_overlap_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.sns_aperture_additions + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.lattice_modifications + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.linac_parsers.rst b/doc/source/modules/orbit.py_linac.linac_parsers.rst new file mode 100644 index 00000000..32e83a62 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.linac_parsers.rst @@ -0,0 +1,25 @@ +orbit.py\_linac.linac\_parsers package +====================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.linac_parsers.jparc_linac_lattice_factory + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.linac_parsers.sns_linac_lattice_factory + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.linac_parsers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.materials.rst b/doc/source/modules/orbit.py_linac.materials.rst new file mode 100644 index 00000000..f777efb7 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.materials.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.materials package +================================= + +Submodules +---------- + + +.. automodule:: orbit.py_linac.materials.VacuumWindowLinacNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.materials + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.orbit_correction.rst b/doc/source/modules/orbit.py_linac.orbit_correction.rst new file mode 100644 index 00000000..1ef126e2 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.orbit_correction.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.orbit\_correction package +========================================= + +Submodules +---------- + + +.. automodule:: orbit.py_linac.orbit_correction.transport_lines_orbit_correction + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.orbit_correction + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.overlapping_fields.rst b/doc/source/modules/orbit.py_linac.overlapping_fields.rst new file mode 100644 index 00000000..9792294c --- /dev/null +++ b/doc/source/modules/orbit.py_linac.overlapping_fields.rst @@ -0,0 +1,31 @@ +orbit.py\_linac.overlapping\_fields package +=========================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.overlapping_fields.jparc_enge_func_factory + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.overlapping_fields.overlapping_quad_fields_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.overlapping_fields.sns_enge_func_factory + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.overlapping_fields + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rf_field_readers.rst b/doc/source/modules/orbit.py_linac.rf_field_readers.rst new file mode 100644 index 00000000..1e48280c --- /dev/null +++ b/doc/source/modules/orbit.py_linac.rf_field_readers.rst @@ -0,0 +1,25 @@ +orbit.py\_linac.rf\_field\_readers package +========================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.rf_field_readers.RF_AxisFieldAnalysis + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.rf_field_readers.SuperFish_3D_RF_FieldReader + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.rf_field_readers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rst b/doc/source/modules/orbit.py_linac.rst new file mode 100644 index 00000000..2678c9f4 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.rst @@ -0,0 +1,25 @@ +orbit.py\_linac package +======================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.py_linac.errors + orbit.py_linac.lattice + orbit.py_linac.lattice_modifications + orbit.py_linac.linac_parsers + orbit.py_linac.materials + orbit.py_linac.orbit_correction + orbit.py_linac.overlapping_fields + orbit.py_linac.rf_field_readers + +Module contents +--------------- + +.. automodule:: orbit.py_linac + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.rf_cavities.rst b/doc/source/modules/orbit.rf_cavities.rst new file mode 100644 index 00000000..c41364a8 --- /dev/null +++ b/doc/source/modules/orbit.rf_cavities.rst @@ -0,0 +1,25 @@ +orbit.rf\_cavities package +========================== + +Submodules +---------- + + +.. automodule:: orbit.rf_cavities.RFLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.rf_cavities.RFNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.rf_cavities + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.rst b/doc/source/modules/orbit.rst new file mode 100644 index 00000000..baa4ca2e --- /dev/null +++ b/doc/source/modules/orbit.rst @@ -0,0 +1,42 @@ +orbit package +============= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.aperture + orbit.bumps + orbit.bunch_generators + orbit.bunch_utils + orbit.collimation + orbit.core + orbit.diagnostics + orbit.errors + orbit.fieldtracker + orbit.foils + orbit.impedances + orbit.injection + orbit.kickernodes + orbit.lattice + orbit.matching + orbit.matrix_lattice + orbit.orbit_correction + orbit.parsers + orbit.py_linac + orbit.rf_cavities + orbit.space_charge + orbit.teapot + orbit.teapot_base + orbit.time_dep + orbit.utils + +Module contents +--------------- + +.. automodule:: orbit + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.directforce2p5d.rst b/doc/source/modules/orbit.space_charge.directforce2p5d.rst new file mode 100644 index 00000000..fd68e4b0 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.directforce2p5d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.directforce2p5d package +=========================================== + +Submodules +---------- + + +.. automodule:: orbit.space_charge.directforce2p5d.directforceAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.directforce2p5d.directforceLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.directforce2p5d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.rst b/doc/source/modules/orbit.space_charge.rst new file mode 100644 index 00000000..1e6c9931 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.rst @@ -0,0 +1,43 @@ +orbit.space\_charge package +=========================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.space_charge.directforce2p5d + orbit.space_charge.sc1d + orbit.space_charge.sc2dslicebyslice + orbit.space_charge.sc2p5d + orbit.space_charge.sc3d + +Submodules +---------- + + +.. automodule:: orbit.space_charge.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sccenteredLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc1d.rst b/doc/source/modules/orbit.space_charge.sc1d.rst new file mode 100644 index 00000000..fc98d94d --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc1d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc1d package +================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc1d.sc1DNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc1d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc1d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst new file mode 100644 index 00000000..b20b40a6 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc2dslicebyslice package +============================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc2dslicebyslice.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc2dslicebyslice.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc2dslicebyslice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2p5d.rst b/doc/source/modules/orbit.space_charge.sc2p5d.rst new file mode 100644 index 00000000..50c704d3 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc2p5d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc2p5d package +================================== + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc2p5d.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc2p5d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc2p5d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc3d.rst b/doc/source/modules/orbit.space_charge.sc3d.rst new file mode 100644 index 00000000..35c82bf1 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc3d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc3d package +================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc3d.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc3d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc3d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.teapot.rst b/doc/source/modules/orbit.teapot.rst new file mode 100644 index 00000000..f924de25 --- /dev/null +++ b/doc/source/modules/orbit.teapot.rst @@ -0,0 +1,25 @@ +orbit.teapot package +==================== + +Submodules +---------- + + +.. automodule:: orbit.teapot.teapot + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.teapot.teapot_matrix_lattice + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.teapot + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.teapot_base.rst b/doc/source/modules/orbit.teapot_base.rst new file mode 100644 index 00000000..97eed985 --- /dev/null +++ b/doc/source/modules/orbit.teapot_base.rst @@ -0,0 +1,10 @@ +orbit.teapot\_base package +========================== + +Module contents +--------------- + +.. automodule:: orbit.teapot_base + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.time_dep.rst b/doc/source/modules/orbit.time_dep.rst new file mode 100644 index 00000000..88c59ecb --- /dev/null +++ b/doc/source/modules/orbit.time_dep.rst @@ -0,0 +1,25 @@ +orbit.time\_dep package +======================= + +Submodules +---------- + + +.. automodule:: orbit.time_dep.time_dep + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.time_dep.waveform + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.time_dep + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.fitting.rst b/doc/source/modules/orbit.utils.fitting.rst new file mode 100644 index 00000000..f1cf43ac --- /dev/null +++ b/doc/source/modules/orbit.utils.fitting.rst @@ -0,0 +1,49 @@ +orbit.utils.fitting package +=========================== + +Submodules +---------- + + +.. automodule:: orbit.utils.fitting.BisectionSearch1D + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.GoldenSectionSearch1D + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.PolynomialFit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.RandomSearch + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.SimplexSearch + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.Solver_lib + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.fitting + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst new file mode 100644 index 00000000..9ac256d8 --- /dev/null +++ b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst @@ -0,0 +1,37 @@ +orbit.utils.orbit\_mpi\_utils package +===================================== + +Submodules +---------- + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit_nHarm + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit_nHarm + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.orbit_mpi_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.rst b/doc/source/modules/orbit.utils.rst new file mode 100644 index 00000000..968b26d9 --- /dev/null +++ b/doc/source/modules/orbit.utils.rst @@ -0,0 +1,65 @@ +orbit.utils package +=================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.utils.fitting + orbit.utils.orbit_mpi_utils + orbit.utils.xml + +Submodules +---------- + + +.. automodule:: orbit.utils.NamedObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.ParamsDictObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.TypedObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.consts + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.multiDimArray + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbitFinalize + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.phaseOperations + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.xml.rst b/doc/source/modules/orbit.utils.xml.rst new file mode 100644 index 00000000..f1ceb913 --- /dev/null +++ b/doc/source/modules/orbit.utils.xml.rst @@ -0,0 +1,19 @@ +orbit.utils.xml package +======================= + +Submodules +---------- + + +.. automodule:: orbit.utils.xml.XmlDataAdaptor + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.xml + :members: + :show-inheritance: + :undoc-members: From d00f6ade00f7d67ddbf145e86abf3d8af80e0a6c Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 16 Dec 2025 12:39:59 -0500 Subject: [PATCH 03/23] autosummary working. Mostly. --- .gitignore | 1 + doc/source/conf.py | 6 +- doc/source/index.rst | 57 ++---- doc/source/install.rst | 193 ++++++++++++++++++ doc/source/{modules/orbit.rst => modules.rst} | 23 +-- doc/source/modules/orbit.aperture.rst | 31 --- doc/source/modules/orbit.bumps.rst | 31 --- doc/source/modules/orbit.bunch_generators.rst | 19 -- doc/source/modules/orbit.bunch_utils.rst | 25 --- doc/source/modules/orbit.collimation.rst | 25 --- doc/source/modules/orbit.core.rst | 10 - doc/source/modules/orbit.diagnostics.rst | 37 ---- doc/source/modules/orbit.errors.rst | 25 --- doc/source/modules/orbit.fieldtracker.rst | 25 --- doc/source/modules/orbit.foils.rst | 25 --- doc/source/modules/orbit.impedances.rst | 25 --- doc/source/modules/orbit.injection.rst | 43 ---- doc/source/modules/orbit.kickernodes.rst | 37 ---- doc/source/modules/orbit.lattice.rst | 37 ---- doc/source/modules/orbit.matching.rst | 19 -- doc/source/modules/orbit.matrix_lattice.rst | 25 --- doc/source/modules/orbit.orbit_correction.rst | 19 -- doc/source/modules/orbit.parsers.rst | 37 ---- doc/source/modules/orbit.py_linac.errors.rst | 19 -- doc/source/modules/orbit.py_linac.lattice.rst | 61 ------ .../orbit.py_linac.lattice_modifications.rst | 49 ----- .../modules/orbit.py_linac.linac_parsers.rst | 25 --- .../modules/orbit.py_linac.materials.rst | 19 -- .../orbit.py_linac.orbit_correction.rst | 19 -- .../orbit.py_linac.overlapping_fields.rst | 31 --- .../orbit.py_linac.rf_field_readers.rst | 25 --- doc/source/modules/orbit.py_linac.rst | 25 --- doc/source/modules/orbit.rf_cavities.rst | 25 --- .../orbit.space_charge.directforce2p5d.rst | 25 --- doc/source/modules/orbit.space_charge.rst | 43 ---- .../modules/orbit.space_charge.sc1d.rst | 25 --- .../orbit.space_charge.sc2dslicebyslice.rst | 25 --- .../modules/orbit.space_charge.sc2p5d.rst | 25 --- .../modules/orbit.space_charge.sc3d.rst | 25 --- doc/source/modules/orbit.teapot.rst | 25 --- doc/source/modules/orbit.teapot_base.rst | 10 - doc/source/modules/orbit.time_dep.rst | 25 --- doc/source/modules/orbit.utils.fitting.rst | 49 ----- .../modules/orbit.utils.orbit_mpi_utils.rst | 37 ---- doc/source/modules/orbit.utils.rst | 65 ------ doc/source/modules/orbit.utils.xml.rst | 19 -- 46 files changed, 218 insertions(+), 1253 deletions(-) create mode 100644 doc/source/install.rst rename doc/source/{modules/orbit.rst => modules.rst} (73%) delete mode 100644 doc/source/modules/orbit.aperture.rst delete mode 100644 doc/source/modules/orbit.bumps.rst delete mode 100644 doc/source/modules/orbit.bunch_generators.rst delete mode 100644 doc/source/modules/orbit.bunch_utils.rst delete mode 100644 doc/source/modules/orbit.collimation.rst delete mode 100644 doc/source/modules/orbit.core.rst delete mode 100644 doc/source/modules/orbit.diagnostics.rst delete mode 100644 doc/source/modules/orbit.errors.rst delete mode 100644 doc/source/modules/orbit.fieldtracker.rst delete mode 100644 doc/source/modules/orbit.foils.rst delete mode 100644 doc/source/modules/orbit.impedances.rst delete mode 100644 doc/source/modules/orbit.injection.rst delete mode 100644 doc/source/modules/orbit.kickernodes.rst delete mode 100644 doc/source/modules/orbit.lattice.rst delete mode 100644 doc/source/modules/orbit.matching.rst delete mode 100644 doc/source/modules/orbit.matrix_lattice.rst delete mode 100644 doc/source/modules/orbit.orbit_correction.rst delete mode 100644 doc/source/modules/orbit.parsers.rst delete mode 100644 doc/source/modules/orbit.py_linac.errors.rst delete mode 100644 doc/source/modules/orbit.py_linac.lattice.rst delete mode 100644 doc/source/modules/orbit.py_linac.lattice_modifications.rst delete mode 100644 doc/source/modules/orbit.py_linac.linac_parsers.rst delete mode 100644 doc/source/modules/orbit.py_linac.materials.rst delete mode 100644 doc/source/modules/orbit.py_linac.orbit_correction.rst delete mode 100644 doc/source/modules/orbit.py_linac.overlapping_fields.rst delete mode 100644 doc/source/modules/orbit.py_linac.rf_field_readers.rst delete mode 100644 doc/source/modules/orbit.py_linac.rst delete mode 100644 doc/source/modules/orbit.rf_cavities.rst delete mode 100644 doc/source/modules/orbit.space_charge.directforce2p5d.rst delete mode 100644 doc/source/modules/orbit.space_charge.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc1d.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc2p5d.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc3d.rst delete mode 100644 doc/source/modules/orbit.teapot.rst delete mode 100644 doc/source/modules/orbit.teapot_base.rst delete mode 100644 doc/source/modules/orbit.time_dep.rst delete mode 100644 doc/source/modules/orbit.utils.fitting.rst delete mode 100644 doc/source/modules/orbit.utils.orbit_mpi_utils.rst delete mode 100644 doc/source/modules/orbit.utils.rst delete mode 100644 doc/source/modules/orbit.utils.xml.rst diff --git a/.gitignore b/.gitignore index 44b61695..cddf9522 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ PyORBIT.egg-info .*.swp .eggs .venv +_autosummary/ diff --git a/doc/source/conf.py b/doc/source/conf.py index 12246764..ee878d1c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,8 +21,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] -autosummary_generate = True napoleon_numpy_docstring = True +autosummary_imported_members = True templates_path = ['_templates'] exclude_patterns = [] @@ -30,9 +30,9 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'furo' +html_theme = 'pydata_sphinx_theme' html_static_path = ['_static'] html_show_source_link = True html_theme_options = { - # 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', + 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', } diff --git a/doc/source/index.rst b/doc/source/index.rst index d16735f7..08e066b4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,54 +3,23 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -PyORBIT3 documentation -====================== +PyORBIT3 +======== -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + install .. toctree:: :maxdepth: 2 :caption: Modules - :hidden: - modules/orbit.aperture - modules/orbit.bump - modules/orbit.bunch_generators - modules/orbit.bunch_utils - modules/orbit.collimation - modules/orbit.diagnostics - modules/orbit.errors - modules/orbit.fieldtracker - modules/orbit.foils - modules/orbit.impedances - modules/orbit.injection - modules/orbit.kickernodes - modules/orbit.lattice - modules/orbit.matching - modules/orbit.matrix_lattice - modules/orbit.orbit_correction - modules/orbit.parsers - modules/orbit.py_linac.errors - modules/orbit.py_linac.lattice - modules/orbit.py_linac.lattice_modifications - modules/orbit.py_linac.linac_parsers - modules/orbit.py_linac.materials - modules/orbit.py_linac.orbit_correction - modules/orbit.py_linac.overlapping_fields - modules/orbit.py_linac.rf_field_readers - modules/orbit.py_linac - modules/orbit.rf_cavities - modules/orbit.space_charge.directforce2p5d - modules/orbit.space_charge - modules/orbit.space_charge.sc1d - modules/orbit.space_charge.sc2dslicebyslice - modules/orbit.space_charge.sc2p5d - modules/orbit.space_charge.sc3d - modules/orbit.teapot - modules/orbit.teapot_base - modules/orbit.time_dep - modules/orbit.utils.fitting - modules/orbit.utils.orbit_mpi_utils + modules + +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 00000000..a8978c20 --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,193 @@ +Installation +============================= + +1. Introduction +--------------- + +This guide provides instructions how to install PyORBIT code. This guide +doesn’t cover MPI enabled installation. The following configurations are +included in CI testing, versions will change as the runner images +progress. + ++------------+-----------+------------+-------+-----------+-----------+ +| HW | Arc | OS | P | Compiler | Package | +| | hitecture | | ython | | | ++============+===========+============+=======+===========+===========+ +| PC | x86_64 | CentOS | 3 | g | pip-24.0 | +| | | latest | .9.18 | cc-11.4.1 | | ++------------+-----------+------------+-------+-----------+-----------+ +| PC | x86_64 | Ubuntu | 3 | g | pip-24.0 | +| | | latest | .12.3 | cc-13.2.0 | | ++------------+-----------+------------+-------+-----------+-----------+ +| Apple | arm64 | macOS 14 | 3 | cla | pip-24.0 | +| Silicon | | | .12.3 | ng-15.0.0 | | ++------------+-----------+------------+-------+-----------+-----------+ +| PC | x86_64 | Ubuntu | 3. | g | con | +| | | latest | 10.14 | cc-13.2.0 | da-24.5.0 | ++------------+-----------+------------+-------+-----------+-----------+ + +2. Installation from source +--------------------------- + +First step is to clone the source code: + +.. code:: bash + + git clone https://github.com/PyORBIT-Collaboration/PyORBIT3.git + +Pip Setup +~~~~~~~~~ + +**PIP** based setup is more involved, we recommend using **conda** if +unsure. #### Prepare OS The following commands may require root access. + +.. raw:: html + +
+ +.. raw:: html + + + +Click for Ubuntu-based distributions + +.. raw:: html + + + +.. code:: bash + + apt-get update + apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + + + +Click for Redhat-based distributions + +.. raw:: html + + + +.. code:: bash + + dnf group install -y "Development Tools" + dnf install -y python3-devel fftw3-devel + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + + + +Click for Mac + +.. raw:: html + + + +Install Homebrew, make sure that homebrew programs are in the **$PATH** +(optional step in Homebrew installation) +``bash brew install pkg-config fftw`` + +.. raw:: html + +
+ +#### Create Python virtual environment Make sure that you have the +correct python version installed. We require python>3.9. Create virtual +environment. +``python3 -m venv .po3 . .po3/bin/activate pip install -U pip pip install -r requirements.txt pip install -U setuptools`` + +Conda Setup +~~~~~~~~~~~ + +First of all make sure you have conda installed and development +packages. Development packages for Ubuntu: + +:: + + apt update -y + apt install -y curl gpg git build-essential + +Then run the following: + +.. code:: bash + + cd pyorbit3 + conda env create -n po3 --file environment.yml + conda activate po3 + pip install -U meson-python setuptools setuptools-scm + +3. Build +-------- + +If you plan to modify PyORBIT’s code, install it in editable mode. You +will NOT need to rebuild after modifications to the code. +`Meson `__ will rebuild as necessary on import. + +:: + + pip install --no-build-isolation --editable . + +Alternatively if you don’t plan to modify PyORBIT’s code + +:: + + pip install . + +4. Run full SNS linac example +----------------------------- + +Navigate to your **examples** directory and launch tracking of SNS +linac. + +.. code:: bash + + cd examples/SNS_Linac/pyorbit3_linac_model/ + python pyorbit3_sns_linac_mebt_hebt2.py + +5. MPI consideration +-------------------- + +By default, the build system will try to find MPI and compile against +it. You can control which MPI to use with command line option when +building. + +.. code:: bash + + pip install --config-settings=setup-args="-DUSE_MPI=none" . + +Above will build PyORBIT without MPI even if MPI is present. You can +change that option to ``mpich``, ``ompi``, ``none`` or ``auto`` +(default). \| MPI flavor \| Installation command \| \|—————\|————–\| \| +No MPI \| +``pip install --config-settings=setup-args="-DUSE_MPI=none" .`` \| \| +The first found MPI installation if any \| +``pip install --config-settings=setup-args="-DUSE_MPI=auto" .`` \| \| +OpenMPI \| +``pip install --config-settings=setup-args="-DUSE_MPI=ompi" .`` \| \| +MPICH \| +``pip install --config-settings=setup-args="-DUSE_MPI=mpich" .`` \| + +Meson uses PKG_CONFIG to discover packages. It could be useful to help +it to find your MPI installation: + +.. code:: bash + + PKG_CONFIG_PATH=/opt/lib/pkgconfig pip install --verbose . diff --git a/doc/source/modules/orbit.rst b/doc/source/modules.rst similarity index 73% rename from doc/source/modules/orbit.rst rename to doc/source/modules.rst index baa4ca2e..1251b4e0 100644 --- a/doc/source/modules/orbit.rst +++ b/doc/source/modules.rst @@ -1,11 +1,12 @@ -orbit package -============= - -Subpackages ------------ - +Modules +======= .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :caption: Modules + +.. autosummary:: + :toctree: _autosummary + :recursive: orbit.aperture orbit.bumps @@ -32,11 +33,3 @@ Subpackages orbit.teapot_base orbit.time_dep orbit.utils - -Module contents ---------------- - -.. automodule:: orbit - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.aperture.rst b/doc/source/modules/orbit.aperture.rst deleted file mode 100644 index 9cf8d713..00000000 --- a/doc/source/modules/orbit.aperture.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.aperture package -====================== - -Submodules ----------- - - -.. automodule:: orbit.aperture.ApertureLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.aperture.ApertureLatticeRangeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.aperture.TeapotApertureNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.aperture - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bumps.rst b/doc/source/modules/orbit.bumps.rst deleted file mode 100644 index 639b975e..00000000 --- a/doc/source/modules/orbit.bumps.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.bumps package -=================== - -Submodules ----------- - - -.. automodule:: orbit.bumps.BumpLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bumps.TeapotBumpNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bumps.bumps - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bumps - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bunch_generators.rst b/doc/source/modules/orbit.bunch_generators.rst deleted file mode 100644 index d2aae682..00000000 --- a/doc/source/modules/orbit.bunch_generators.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.bunch\_generators package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.bunch_generators.distribution_generators - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bunch_generators - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bunch_utils.rst b/doc/source/modules/orbit.bunch_utils.rst deleted file mode 100644 index 35d80b35..00000000 --- a/doc/source/modules/orbit.bunch_utils.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.bunch\_utils package -========================== - -Submodules ----------- - - -.. automodule:: orbit.bunch_utils.particleidnumber - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bunch_utils.serialize - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bunch_utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.collimation.rst b/doc/source/modules/orbit.collimation.rst deleted file mode 100644 index b6100fdb..00000000 --- a/doc/source/modules/orbit.collimation.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.collimation package -========================= - -Submodules ----------- - - -.. automodule:: orbit.collimation.TeapotCollimatorNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.collimation.collimationLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.collimation - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.core.rst b/doc/source/modules/orbit.core.rst deleted file mode 100644 index 53921b7d..00000000 --- a/doc/source/modules/orbit.core.rst +++ /dev/null @@ -1,10 +0,0 @@ -orbit.core package -================== - -Module contents ---------------- - -.. automodule:: orbit.core - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.diagnostics.rst b/doc/source/modules/orbit.diagnostics.rst deleted file mode 100644 index 454b5406..00000000 --- a/doc/source/modules/orbit.diagnostics.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.diagnostics package -========================= - -Submodules ----------- - - -.. automodule:: orbit.diagnostics.TeapotDiagnosticsNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.diagnostics - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.diagnosticsLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.profiles - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.diagnostics - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.errors.rst b/doc/source/modules/orbit.errors.rst deleted file mode 100644 index 8ff1deb7..00000000 --- a/doc/source/modules/orbit.errors.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.errors package -==================== - -Submodules ----------- - - -.. automodule:: orbit.errors.ErrorLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.errors.ErrorNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.errors - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.fieldtracker.rst b/doc/source/modules/orbit.fieldtracker.rst deleted file mode 100644 index bba5190f..00000000 --- a/doc/source/modules/orbit.fieldtracker.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.fieldtracker package -========================== - -Submodules ----------- - - -.. automodule:: orbit.fieldtracker.TeapotFieldLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.fieldtracker.TeapotFieldTrackerNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.fieldtracker - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.foils.rst b/doc/source/modules/orbit.foils.rst deleted file mode 100644 index 6d1c11b4..00000000 --- a/doc/source/modules/orbit.foils.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.foils package -=================== - -Submodules ----------- - - -.. automodule:: orbit.foils.TeapotFoilNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.foils.foilLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.foils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.impedances.rst b/doc/source/modules/orbit.impedances.rst deleted file mode 100644 index 4c540fb2..00000000 --- a/doc/source/modules/orbit.impedances.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.impedances package -======================== - -Submodules ----------- - - -.. automodule:: orbit.impedances.ImpedanceLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.impedances.ImpedanceNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.impedances - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.injection.rst b/doc/source/modules/orbit.injection.rst deleted file mode 100644 index f5b4963e..00000000 --- a/doc/source/modules/orbit.injection.rst +++ /dev/null @@ -1,43 +0,0 @@ -orbit.injection package -======================= - -Submodules ----------- - - -.. automodule:: orbit.injection.InjectionLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.TeapotInjectionNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.distributions - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.injectparticles - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.joho - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.injection - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.kickernodes.rst b/doc/source/modules/orbit.kickernodes.rst deleted file mode 100644 index 2b000f0b..00000000 --- a/doc/source/modules/orbit.kickernodes.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.kickernodes package -========================= - -Submodules ----------- - - -.. automodule:: orbit.kickernodes.KickerLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.TeapotKickerNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.kicker - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.waveforms - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.kickernodes - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.lattice.rst b/doc/source/modules/orbit.lattice.rst deleted file mode 100644 index 68ed9568..00000000 --- a/doc/source/modules/orbit.lattice.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.lattice package -===================== - -Submodules ----------- - - -.. automodule:: orbit.lattice.AccActionsContainer - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccLattice - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccNodeBunchTracker - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.matching.rst b/doc/source/modules/orbit.matching.rst deleted file mode 100644 index 020f4937..00000000 --- a/doc/source/modules/orbit.matching.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.matching package -====================== - -Submodules ----------- - - -.. automodule:: orbit.matching.matching - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.matching - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.matrix_lattice.rst b/doc/source/modules/orbit.matrix_lattice.rst deleted file mode 100644 index b88fc3c4..00000000 --- a/doc/source/modules/orbit.matrix_lattice.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.matrix\_lattice package -============================= - -Submodules ----------- - - -.. automodule:: orbit.matrix_lattice.BaseMATRIX - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.matrix_lattice.MATRIX_Lattice - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.matrix_lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.orbit_correction.rst b/doc/source/modules/orbit.orbit_correction.rst deleted file mode 100644 index 87d458d1..00000000 --- a/doc/source/modules/orbit.orbit_correction.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.orbit\_correction package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.orbit_correction.orbit_correction - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.orbit_correction - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.parsers.rst b/doc/source/modules/orbit.parsers.rst deleted file mode 100644 index 8fffb512..00000000 --- a/doc/source/modules/orbit.parsers.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.parsers package -===================== - -Submodules ----------- - - -.. automodule:: orbit.parsers.field_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.mad_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.madx_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.sad_parser - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.parsers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.errors.rst b/doc/source/modules/orbit.py_linac.errors.rst deleted file mode 100644 index 304668e5..00000000 --- a/doc/source/modules/orbit.py_linac.errors.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.errors package -============================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.errors.ErrorNodesAndControllersLib - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.errors - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice.rst b/doc/source/modules/orbit.py_linac.lattice.rst deleted file mode 100644 index 08f273fb..00000000 --- a/doc/source/modules/orbit.py_linac.lattice.rst +++ /dev/null @@ -1,61 +0,0 @@ -orbit.py\_linac.lattice package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.lattice.LinacAccLatticeFunc - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacAccLatticeLib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacApertureNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacDiagnosticsNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacFieldOverlappingNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacRfGapNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacTransportMatrixGenNodes - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice_modifications.rst b/doc/source/modules/orbit.py_linac.lattice_modifications.rst deleted file mode 100644 index a04b7547..00000000 --- a/doc/source/modules/orbit.py_linac.lattice_modifications.rst +++ /dev/null @@ -1,49 +0,0 @@ -orbit.py\_linac.lattice\_modifications package -============================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.lattice_modifications.apertures_additions_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.errors_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.quad_overlap_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.rf_models_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.rf_quad_overlap_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.sns_aperture_additions - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.lattice_modifications - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.linac_parsers.rst b/doc/source/modules/orbit.py_linac.linac_parsers.rst deleted file mode 100644 index 32e83a62..00000000 --- a/doc/source/modules/orbit.py_linac.linac_parsers.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac.linac\_parsers package -====================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.linac_parsers.jparc_linac_lattice_factory - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.linac_parsers.sns_linac_lattice_factory - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.linac_parsers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.materials.rst b/doc/source/modules/orbit.py_linac.materials.rst deleted file mode 100644 index f777efb7..00000000 --- a/doc/source/modules/orbit.py_linac.materials.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.materials package -================================= - -Submodules ----------- - - -.. automodule:: orbit.py_linac.materials.VacuumWindowLinacNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.materials - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.orbit_correction.rst b/doc/source/modules/orbit.py_linac.orbit_correction.rst deleted file mode 100644 index 1ef126e2..00000000 --- a/doc/source/modules/orbit.py_linac.orbit_correction.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.orbit\_correction package -========================================= - -Submodules ----------- - - -.. automodule:: orbit.py_linac.orbit_correction.transport_lines_orbit_correction - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.orbit_correction - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.overlapping_fields.rst b/doc/source/modules/orbit.py_linac.overlapping_fields.rst deleted file mode 100644 index 9792294c..00000000 --- a/doc/source/modules/orbit.py_linac.overlapping_fields.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.py\_linac.overlapping\_fields package -=========================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.overlapping_fields.jparc_enge_func_factory - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.overlapping_fields.overlapping_quad_fields_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.overlapping_fields.sns_enge_func_factory - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.overlapping_fields - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rf_field_readers.rst b/doc/source/modules/orbit.py_linac.rf_field_readers.rst deleted file mode 100644 index 1e48280c..00000000 --- a/doc/source/modules/orbit.py_linac.rf_field_readers.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac.rf\_field\_readers package -========================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.rf_field_readers.RF_AxisFieldAnalysis - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.rf_field_readers.SuperFish_3D_RF_FieldReader - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.rf_field_readers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rst b/doc/source/modules/orbit.py_linac.rst deleted file mode 100644 index 2678c9f4..00000000 --- a/doc/source/modules/orbit.py_linac.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac package -======================= - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.py_linac.errors - orbit.py_linac.lattice - orbit.py_linac.lattice_modifications - orbit.py_linac.linac_parsers - orbit.py_linac.materials - orbit.py_linac.orbit_correction - orbit.py_linac.overlapping_fields - orbit.py_linac.rf_field_readers - -Module contents ---------------- - -.. automodule:: orbit.py_linac - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.rf_cavities.rst b/doc/source/modules/orbit.rf_cavities.rst deleted file mode 100644 index c41364a8..00000000 --- a/doc/source/modules/orbit.rf_cavities.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.rf\_cavities package -========================== - -Submodules ----------- - - -.. automodule:: orbit.rf_cavities.RFLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.rf_cavities.RFNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.rf_cavities - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.directforce2p5d.rst b/doc/source/modules/orbit.space_charge.directforce2p5d.rst deleted file mode 100644 index fd68e4b0..00000000 --- a/doc/source/modules/orbit.space_charge.directforce2p5d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.directforce2p5d package -=========================================== - -Submodules ----------- - - -.. automodule:: orbit.space_charge.directforce2p5d.directforceAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.directforce2p5d.directforceLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.directforce2p5d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.rst b/doc/source/modules/orbit.space_charge.rst deleted file mode 100644 index 1e6c9931..00000000 --- a/doc/source/modules/orbit.space_charge.rst +++ /dev/null @@ -1,43 +0,0 @@ -orbit.space\_charge package -=========================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.space_charge.directforce2p5d - orbit.space_charge.sc1d - orbit.space_charge.sc2dslicebyslice - orbit.space_charge.sc2p5d - orbit.space_charge.sc3d - -Submodules ----------- - - -.. automodule:: orbit.space_charge.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sccenteredLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc1d.rst b/doc/source/modules/orbit.space_charge.sc1d.rst deleted file mode 100644 index fc98d94d..00000000 --- a/doc/source/modules/orbit.space_charge.sc1d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc1d package -================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc1d.sc1DNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc1d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc1d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst deleted file mode 100644 index b20b40a6..00000000 --- a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc2dslicebyslice package -============================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc2dslicebyslice.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc2dslicebyslice.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc2dslicebyslice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2p5d.rst b/doc/source/modules/orbit.space_charge.sc2p5d.rst deleted file mode 100644 index 50c704d3..00000000 --- a/doc/source/modules/orbit.space_charge.sc2p5d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc2p5d package -================================== - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc2p5d.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc2p5d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc2p5d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc3d.rst b/doc/source/modules/orbit.space_charge.sc3d.rst deleted file mode 100644 index 35c82bf1..00000000 --- a/doc/source/modules/orbit.space_charge.sc3d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc3d package -================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc3d.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc3d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc3d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.teapot.rst b/doc/source/modules/orbit.teapot.rst deleted file mode 100644 index f924de25..00000000 --- a/doc/source/modules/orbit.teapot.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.teapot package -==================== - -Submodules ----------- - - -.. automodule:: orbit.teapot.teapot - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.teapot.teapot_matrix_lattice - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.teapot - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.teapot_base.rst b/doc/source/modules/orbit.teapot_base.rst deleted file mode 100644 index 97eed985..00000000 --- a/doc/source/modules/orbit.teapot_base.rst +++ /dev/null @@ -1,10 +0,0 @@ -orbit.teapot\_base package -========================== - -Module contents ---------------- - -.. automodule:: orbit.teapot_base - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.time_dep.rst b/doc/source/modules/orbit.time_dep.rst deleted file mode 100644 index 88c59ecb..00000000 --- a/doc/source/modules/orbit.time_dep.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.time\_dep package -======================= - -Submodules ----------- - - -.. automodule:: orbit.time_dep.time_dep - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.time_dep.waveform - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.time_dep - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.fitting.rst b/doc/source/modules/orbit.utils.fitting.rst deleted file mode 100644 index f1cf43ac..00000000 --- a/doc/source/modules/orbit.utils.fitting.rst +++ /dev/null @@ -1,49 +0,0 @@ -orbit.utils.fitting package -=========================== - -Submodules ----------- - - -.. automodule:: orbit.utils.fitting.BisectionSearch1D - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.GoldenSectionSearch1D - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.PolynomialFit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.RandomSearch - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.SimplexSearch - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.Solver_lib - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.fitting - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst deleted file mode 100644 index 9ac256d8..00000000 --- a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.utils.orbit\_mpi\_utils package -===================================== - -Submodules ----------- - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit_nHarm - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit_nHarm - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.orbit_mpi_utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.rst b/doc/source/modules/orbit.utils.rst deleted file mode 100644 index 968b26d9..00000000 --- a/doc/source/modules/orbit.utils.rst +++ /dev/null @@ -1,65 +0,0 @@ -orbit.utils package -=================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.utils.fitting - orbit.utils.orbit_mpi_utils - orbit.utils.xml - -Submodules ----------- - - -.. automodule:: orbit.utils.NamedObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.ParamsDictObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.TypedObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.consts - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.multiDimArray - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbitFinalize - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.phaseOperations - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.xml.rst b/doc/source/modules/orbit.utils.xml.rst deleted file mode 100644 index f1ceb913..00000000 --- a/doc/source/modules/orbit.utils.xml.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.utils.xml package -======================= - -Submodules ----------- - - -.. automodule:: orbit.utils.xml.XmlDataAdaptor - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.xml - :members: - :show-inheritance: - :undoc-members: From d27954c581154b68c0ba940f6034687b310bda4b Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 18 Dec 2025 15:34:36 -0500 Subject: [PATCH 04/23] Doxygen + breathe + exhale --- doc/.gitignore | 2 ++ doc/Makefile | 6 +++++- doc/source/conf.py | 30 +++++++++++++++++++++++++++++- doc/source/index.rst | 6 ++++++ 4 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..ca5796cb --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +_doxygen +source/api diff --git a/doc/Makefile b/doc/Makefile index d0c3cbf1..dc706e6c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,9 +12,13 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile clean # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index ee878d1c..22a6cd8c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -20,13 +20,41 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] +extensions = ['sphinx.ext.coverage', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.napoleon', + 'breathe', + 'exhale'] napoleon_numpy_docstring = True autosummary_imported_members = True templates_path = ['_templates'] exclude_patterns = [] +# -- Breathe and Exhale Options --------------------------------------------------------- +breathe_projects = { + "PyORBIT3": "./_doxygen/xml", + } +breathe_default_project = "PyORBIT3" + +doxyfile = '\n'.join([ + "INPUT = ../../src", + "EXCLUDE_PATTERNS = *wrap*", + ]) + +exhale_args = { + "containmentFolder": "./api", + "rootFileName": "pyorbit_root.rst", + "doxygenStripFromPath": "..", + "rootFileTitle": "PyORBIT3 API", + "createTreeView": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": doxyfile, + } + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/doc/source/index.rst b/doc/source/index.rst index 08e066b4..5c29b916 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,6 +18,12 @@ PyORBIT3 modules +.. toctree:: + :maxdepth: 2 + :caption: C++ Interface + + api/pyorbit_root.rst + Indices and tables ================== * :ref:`genindex` From d49472c577145a5badb45a4cdc1f0823e1a539f7 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 18 Dec 2025 15:36:40 -0500 Subject: [PATCH 05/23] Should be api not _api --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index dc706e6c..16b56424 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 22bd75e3fa34d959ad108e50494ad70e402420fa Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 8 Jan 2026 17:10:42 -0500 Subject: [PATCH 06/23] Remove duplicates in C++ docs Resolved an issue where some of the C++ side of PyORBIT was getting documented twice. Ignored some macros that were causing errors while building documentation. Documentated a couple of methods as examples. --- doc/Makefile | 2 +- doc/source/conf.py | 10 +- doc/source/index.rst | 2 +- doc/source/modules.rst | 11 +- docs-environment.yml | 139 ++++++++++++++++++ src/mpi/orbit_mpi.cc | 2 + .../BunchDiagnostics/BunchTwissAnalysis.cc | 4 - .../BunchDiagnostics/BunchTwissAnalysis.hh | 11 +- src/orbit/MaterialInteractions/numrecipes.cc | 9 +- src/orbit/MaterialInteractions/numrecipes.hh | 49 +++++- .../UniformEllipsoidFieldCalculator.cc | 2 + src/utils/Random.cc | 2 + 12 files changed, 229 insertions(+), 14 deletions(-) create mode 100644 docs-environment.yml diff --git a/doc/Makefile b/doc/Makefile index 16b56424..e5bfb095 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api "$(SOURCEDIR)"/_autosummary @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index 22a6cd8c..1a9dc3d4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -5,6 +5,7 @@ # -- Path setup -------------------------------------------------------------- import sys +import pathlib from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) @@ -42,14 +43,16 @@ doxyfile = '\n'.join([ "INPUT = ../../src", - "EXCLUDE_PATTERNS = *wrap*", + "EXCLUDE_PATTERNS = *wrap* *_init.cc", + "PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS", + "PREDEFINED += PyObject_HEAD=\"PyObject ob_base;\"" ]) exhale_args = { "containmentFolder": "./api", "rootFileName": "pyorbit_root.rst", "doxygenStripFromPath": "..", - "rootFileTitle": "PyORBIT3 API", + "rootFileTitle": "PyORBIT3 C++ API", "createTreeView": True, "exhaleExecutesDoxygen": True, "exhaleDoxygenStdin": doxyfile, @@ -63,4 +66,7 @@ html_show_source_link = True html_theme_options = { 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', + 'logo': { + 'text': "PyORBIT3", + } } diff --git a/doc/source/index.rst b/doc/source/index.rst index 5c29b916..7d38cecb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -20,7 +20,7 @@ PyORBIT3 .. toctree:: :maxdepth: 2 - :caption: C++ Interface + :caption: C++ API api/pyorbit_root.rst diff --git a/doc/source/modules.rst b/doc/source/modules.rst index 1251b4e0..d8cb2ccd 100644 --- a/doc/source/modules.rst +++ b/doc/source/modules.rst @@ -5,7 +5,7 @@ Modules :caption: Modules .. autosummary:: - :toctree: _autosummary + :toctree: _autosummary/ :recursive: orbit.aperture @@ -26,7 +26,14 @@ Modules orbit.matrix_lattice orbit.orbit_correction orbit.parsers - orbit.py_linac + orbit.py_linac.errors + orbit.py_linac.lattice + orbit.py_linac.lattice_modifications + orbit.py_linac.linac_parsers + orbit.py_linac.materials + orbit.py_linac.orbit_correction + orbit.py_linac.overlapping_fields + orbit.py_linac.rf_field_readers orbit.rf_cavities orbit.space_charge orbit.teapot diff --git a/docs-environment.yml b/docs-environment.yml new file mode 100644 index 00000000..79a24a96 --- /dev/null +++ b/docs-environment.yml @@ -0,0 +1,139 @@ +name: docs +channels: + - conda-forge +dependencies: + - _openmp_mutex=4.5=7_kmp_llvm + - accessible-pygments=0.0.5=pyhd8ed1ab_1 + - alabaster=0.7.16=pyhd8ed1ab_0 + - babel=2.17.0=pyhd8ed1ab_0 + - backports.zstd=1.2.0=py313hf42fe89_0 + - beautifulsoup4=4.14.3=pyha770c72_0 + - black=25.12.0=pyh866005b_0 + - breathe=4.35.0=pyhd8ed1ab_4 + - brotli=1.2.0=h7d5ae5b_1 + - brotli-bin=1.2.0=hc919400_1 + - brotli-python=1.2.0=py313hde1f3bb_1 + - bzip2=1.0.8=hd037594_8 + - c-ares=1.34.6=hc919400_0 + - ca-certificates=2025.11.12=hbd8a1cb_0 + - certifi=2025.11.12=pyhd8ed1ab_0 + - charset-normalizer=3.4.4=pyhd8ed1ab_0 + - click=8.3.1=pyh8f84b5b_1 + - colorama=0.4.6=pyhd8ed1ab_1 + - contourpy=1.3.3=py313ha61f8ec_3 + - cycler=0.12.1=pyhcf101f3_2 + - docutils=0.17.1=py313h8f79df9_7 + - doxygen=1.13.2=h493aca8_0 + - exhale=0.3.7=pyhd8ed1ab_1 + - fonttools=4.61.1=pyh7db6752_0 + - freetype=2.14.1=hce30654_0 + - h2=4.3.0=pyhcf101f3_0 + - hpack=4.1.0=pyhd8ed1ab_0 + - hyperframe=6.1.0=pyhd8ed1ab_0 + - icu=75.1=hfee45f7_0 + - idna=3.11=pyhd8ed1ab_0 + - imagesize=1.4.1=pyhd8ed1ab_0 + - importlib-metadata=8.7.0=pyhe01879c_1 + - isort=7.0.0=pyhd8ed1ab_0 + - jinja2=3.1.6=pyhcf101f3_1 + - kiwisolver=1.4.9=py313h7add70c_2 + - lcms2=2.17=h7eeda09_0 + - lerc=4.0.0=hd64df32_1 + - libabseil=20250512.1=cxx17_hd41c47c_0 + - libblas=3.11.0=5_h51639a9_openblas + - libbrotlicommon=1.2.0=hc919400_1 + - libbrotlidec=1.2.0=hc919400_1 + - libbrotlienc=1.2.0=hc919400_1 + - libcblas=3.11.0=5_hb0561ab_openblas + - libcxx=21.1.8=hf598326_0 + - libdeflate=1.25=hc11a715_0 + - libev=4.33=h93a5062_2 + - libevent=2.1.12=h2757513_1 + - libexpat=2.7.3=haf25636_0 + - libfabric=2.4.0=hce30654_0 + - libfabric1=2.4.0=hc919400_0 + - libffi=3.5.2=he5f378a_0 + - libfreetype=2.14.1=hce30654_0 + - libfreetype6=2.14.1=h6da58f4_0 + - libgcc=15.2.0=hcbb3090_16 + - libgfortran=15.2.0=h07b0088_16 + - libgfortran5=15.2.0=hdae7583_16 + - libhwloc=2.12.1=default_ha3cc4f2_1003 + - libiconv=1.18=h23cfdf5_2 + - libjpeg-turbo=3.1.2=hc919400_0 + - liblapack=3.11.0=5_hd9741b5_openblas + - liblzma=5.8.1=h39f12f2_2 + - libmpdec=4.0.0=h5505292_0 + - libnghttp2=1.67.0=hc438710_0 + - libopenblas=0.3.30=openmp_ha158390_3 + - libpmix=5.0.8=h3e7ebac_2 + - libpng=1.6.53=hfab5511_0 + - libsqlite=3.51.1=h9a5124b_0 + - libtiff=4.7.1=h4030677_1 + - libuv=1.51.0=h6caf38d_1 + - libwebp-base=1.6.0=h07db88b_0 + - libxcb=1.17.0=hdb1d25a_0 + - libxml2=2.15.1=h9329255_0 + - libxml2-16=2.15.1=h0ff4647_0 + - libxslt=1.1.43=hb2570ba_1 + - libzlib=1.3.1=h8359307_2 + - llvm-openmp=21.1.8=h4a912ad_0 + - lxml=6.0.2=py313he6cafaa_2 + - markupsafe=3.0.3=pyh7db6752_0 + - matplotlib=3.10.8=py313h39782a4_0 + - matplotlib-base=3.10.8=py313h58042b9_0 + - mpi=1.0.1=openmpi + - munkres=1.1.4=pyhd8ed1ab_1 + - mypy_extensions=1.1.0=pyha770c72_0 + - ncurses=6.5=h5e97a16_3 + - nodeenv=1.9.1=pyhd8ed1ab_1 + - nodejs=25.2.1=h5230ea7_1 + - numpy=2.3.5=py313h9771d21_0 + - openjpeg=2.5.4=hbfb3c88_0 + - openmpi=5.0.8=h13a75e3_109 + - openssl=3.6.0=h5503f6c_0 + - packaging=25.0=pyh29332c3_1 + - pathspec=0.12.1=pyhd8ed1ab_1 + - pillow=12.0.0=py313ha86496b_2 + - pip=25.3=pyh145f28c_0 + - platformdirs=4.5.1=pyhcf101f3_0 + - pthread-stubs=0.4=hd74edd7_1002 + - pydata-sphinx-theme=0.13.3=pyhd8ed1ab_0 + - pygments=2.19.2=pyhd8ed1ab_0 + - pyparsing=3.2.5=pyhcf101f3_0 + - pyright=1.1.407=py313h9734d34_0 + - pysocks=1.7.1=pyha55dd90_7 + - python=3.13.11=hfc2f54d_100_cp313 + - python-dateutil=2.9.0.post0=pyhe01879c_2 + - python_abi=3.13=8_cp313 + - pytokens=0.3.0=pyhcf101f3_0 + - pytz=2025.2=pyhd8ed1ab_0 + - qhull=2020.2=h420ef59_5 + - readline=8.3=h46df422_0 + - requests=2.32.5=pyhd8ed1ab_0 + - roman-numerals=4.1.0=pyhd8ed1ab_0 + - scipy=1.16.3=py313h0d10b07_1 + - setuptools=80.9.0=pyhff2d567_0 + - six=1.17.0=pyhe01879c_1 + - snowballstemmer=3.0.1=pyhd8ed1ab_0 + - soupsieve=2.8=pyhd8ed1ab_0 + - sphinx=4.5.0=pyh6c4a22f_0 + - sphinxcontrib-applehelp=1.0.4=pyhd8ed1ab_0 + - sphinxcontrib-devhelp=1.0.2=py_0 + - sphinxcontrib-htmlhelp=2.0.1=pyhd8ed1ab_0 + - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_1 + - sphinxcontrib-qthelp=1.0.3=py_0 + - sphinxcontrib-serializinghtml=1.1.5=pyhd8ed1ab_2 + - standard-imghdr=3.13.0=pyh29332c3_0 + - tk=8.6.13=h892fb3f_3 + - tornado=6.5.4=py313h6535dbc_0 + - typing-extensions=4.15.0=h396c80c_0 + - typing_extensions=4.15.0=pyhcf101f3_0 + - tzdata=2025c=h8577fbf_0 + - unicodedata2=17.0.0=py313h6535dbc_1 + - urllib3=2.6.2=pyhd8ed1ab_0 + - xorg-libxau=1.0.12=hc919400_1 + - xorg-libxdmcp=1.1.5=hc919400_1 + - zipp=3.23.0=pyhcf101f3_1 + - zlib-ng=2.3.2=h248ca61_0 + - zstd=1.5.7=hbf9d68e_6 diff --git a/src/mpi/orbit_mpi.cc b/src/mpi/orbit_mpi.cc index 8a36065e..2dc97e71 100644 --- a/src/mpi/orbit_mpi.cc +++ b/src/mpi/orbit_mpi.cc @@ -5,6 +5,7 @@ #include #include +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) /** A C wrapper around MPI_Init. */ int ORBIT_MPI_Init(){ int res = 0; @@ -620,3 +621,4 @@ int ORBIT_MPI_Get_count(MPI_Status *status, MPI_Datatype datatype, int *count){ #endif return res; } +#endif // !defined(DOXYGEN_SHOULD_SKIP_THIS) diff --git a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc index 2063b6ae..0a361326 100644 --- a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc +++ b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc @@ -337,10 +337,6 @@ void BunchTwissAnalysis::computeBunchMoments(Bunch* bunch, int order, int disper } - - - -/** Returns the centered correlation <(x-)*(y-)> = - * */ double BunchTwissAnalysis::getCorrelation(int ic, int jc){ if(ic < 0 || ic > 5 || jc < 0 || jc >5) return 0.; return (corr_arr[ic+6*jc] - avg_arr[ic]* avg_arr[jc]); diff --git a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh index df6e2b4b..deaa20ee 100644 --- a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh +++ b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh @@ -26,7 +26,16 @@ class BunchTwissAnalysis: public OrbitUtils::CppPyWrapper /** Performs the Twiss analysis of the bunch */ void analyzeBunch(Bunch* bunch); - /** Returns the centered correlation <(x-)*(y-)> = - * */ + /** + * @brief Returns the centered correlation between two components. + * + * \f$\langle (x-\langle x\rangle)(y-\langle y\rangle)\rangle + * = \langle x y\rangle - \langle x\rangle\langle y\rangle\f$ + * + * @param ic Index of the first component (x). + * @param jc Index of the second component (y). + * @return The centered correlation value as a double. + */ double getCorrelation(int ic, int jc); /** Returns the average value for coordinate with index ic */ diff --git a/src/orbit/MaterialInteractions/numrecipes.cc b/src/orbit/MaterialInteractions/numrecipes.cc index eadd37ee..a38dd327 100644 --- a/src/orbit/MaterialInteractions/numrecipes.cc +++ b/src/orbit/MaterialInteractions/numrecipes.cc @@ -29,9 +29,8 @@ namespace OrbitUtils{ return sin(x)*exp(-fac1*pow(2*p*sin(x/2), 2))/pow(sin(x/2),4); } - int zbrak(float (*fx)(float, float, float, float), float x1, float x2, - int n, float xb1[], float xb2[], int &nb, float param1, + int n, float *xb1, float *xb2, int &nb, float param1, float param2, float param3) { int nbb, i; @@ -54,7 +53,9 @@ namespace OrbitUtils{ } #undef JMAX +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define JMAX 40 +#endif float rtbis(float (*func)(float, float, float, float), float x1, float x2, float xacc, float param1, float param2, float param3) @@ -134,8 +135,10 @@ namespace OrbitUtils{ #undef EPS #undef JMAX +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define EPS 1.0e-6 #define JMAX 20 +#endif float qsimp(float (*func)(float, float, float), float a, float b, float p, float fac1) @@ -164,7 +167,9 @@ namespace OrbitUtils{ /* note #undef's at end of file */ +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define FUNC(x, p, fac1) ((*rfunc)(x, p, fac1)) +#endif float trapzd(float (*rfunc)(float, float, float), float a, float b, int n, float p, float fac1) diff --git a/src/orbit/MaterialInteractions/numrecipes.hh b/src/orbit/MaterialInteractions/numrecipes.hh index 25f884e0..8059db80 100644 --- a/src/orbit/MaterialInteractions/numrecipes.hh +++ b/src/orbit/MaterialInteractions/numrecipes.hh @@ -16,7 +16,54 @@ namespace OrbitUtils{ float fstep(float s, float r_o, float pr_o, float theta); float rfunc(float x, float p, float fac1); - int zbrak(float (*fx)(float, float, float, float), float x1, float x2, int n, float xb1[], float xb2[], int &nb, float param1, + + /** + * @brief Bracket subintervals where a function changes sign. + * + * Scans the interval [x1, x2] by dividing it into @p n equal subintervals + * and records subinterval endpoints where the function @p fx changes sign + * (i.e., a root is bracketed). + * + * The function @p fx must have the signature: + * float fx(float x, float p1, float p2, float p3); + * It is evaluated at the grid points x1, x1 + dx, x1 + 2*dx, ..., x2, + * where dx = (x2 - x1) / n. + * + * When an interval [xb1[k], xb2[k]] is found such that fx(xb1[k]) and + * fx(xb2[k]) have opposite signs (fc*fp <= 0), the endpoints are stored + * in the output arrays xb1 and xb2 at the same index k (1-based indexing + * is used internally; the caller should account for this). + * + * @param fx Pointer to the function to examine. Signature: + * float fx(float x, float param1, float param2, float param3). + * @param x1 Left end of the search interval. + * @param x2 Right end of the search interval. + * @param n Number of equal subintervals to split [x1, x2] into. + * @param xb1 Output array to receive left endpoints of bracketing subintervals. + * Must be large enough to hold up to the capacity indicated by the + * integer referenced by @p nb (see @p nb description). + * @param xb2 Output array to receive right endpoints of bracketing subintervals. + * Same required capacity as @p xb1. + * @param nb Reference to an integer indicating the maximum number of bracket + * intervals the caller can accept on input; on return this integer + * is set to the actual number of brackets found (nb <= original nb). + * @param param1 First user parameter passed through to @p fx. + * @param param2 Second user parameter passed through to @p fx. + * @param param3 Third user parameter passed through to @p fx. + * + * @return Returns 0 on completion. If the number of found brackets reaches the + * input capacity (nb), the function returns immediately with xb1/xb2 + * filled up to that capacity and nb set equal to that capacity. + * + * @note + * - The function uses sequential evaluations of @p fx and treats a zero or a + * sign change (fc*fp <= 0.0) as a bracket. Adjacent subintervals that both + * satisfy this condition will each be reported. + * - The implementation uses 1-based indexing internally when filling xb1/xb2. + * The caller should allocate arrays accordingly and interpret the filled + * entries consistent with the calling convention used in the surrounding code. + */ + int zbrak(float (*fx)(float, float, float, float), float x1, float x2, int n, float *xb1, float *xb2, int &nb, float param1, float param2, float param3); float rtbis(float (*func)(float, float, float, float), float x1, float x2, float xacc, float param1, float param2, float param3); float bessj0(float x); diff --git a/src/spacecharge/UniformEllipsoidFieldCalculator.cc b/src/spacecharge/UniformEllipsoidFieldCalculator.cc index 42fc6970..811eb52d 100644 --- a/src/spacecharge/UniformEllipsoidFieldCalculator.cc +++ b/src/spacecharge/UniformEllipsoidFieldCalculator.cc @@ -15,6 +15,7 @@ using namespace OrbitUtils; //macros for max and min +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #ifndef max #define max( a, b ) ( ((a) > (b)) ? (a) : (b) ) #endif @@ -22,6 +23,7 @@ using namespace OrbitUtils; #ifndef min #define min( a, b ) ( ((a) < (b)) ? (a) : (b) ) #endif +#endif /** Constructor. There is no parameters */ UniformEllipsoidFieldCalculator::UniformEllipsoidFieldCalculator(): CppPyWrapper(NULL) diff --git a/src/utils/Random.cc b/src/utils/Random.cc index c19bafca..4725232a 100644 --- a/src/utils/Random.cc +++ b/src/utils/Random.cc @@ -21,6 +21,7 @@ using namespace OrbitUtils; // By default the random generator is initialized using a random seed (current time) +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) std::mt19937 mt(time(0)); void Random::seed(int seed){ @@ -31,3 +32,4 @@ void Random::seed(int seed){ double Random::ran1(){ return ((double) mt() / (mt.max())); } +#endif From 245063c7bb9d7698521bb11c73bbc10dd2b94e87 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 15 Dec 2025 20:08:31 -0500 Subject: [PATCH 07/23] init sphinx --- .gitignore | 1 + doc/Makefile | 20 ++++++++++++++++++++ doc/make.bat | 35 +++++++++++++++++++++++++++++++++++ doc/placeholder | 0 doc/source/conf.py | 28 ++++++++++++++++++++++++++++ doc/source/index.rst | 17 +++++++++++++++++ 6 files changed, 101 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/make.bat delete mode 100644 doc/placeholder create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/.gitignore b/.gitignore index 47650c0e..44b61695 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ PyORBIT.egg-info *.so .*.swp .eggs +.venv diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/placeholder b/doc/placeholder deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..83bb65fd --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'PyORBIT3' +copyright = '2025, PyORBIT Collaboration' +author = 'PyORBIT Collaboration' +release = 'v3.0.1' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..dfd70787 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,17 @@ +.. PyORBIT3 documentation master file, created by + sphinx-quickstart on Mon Dec 15 20:07:23 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +PyORBIT3 documentation +====================== + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + From 12c9437996be38e2b7f929c6d143d69dda228c13 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 15 Dec 2025 20:19:03 -0500 Subject: [PATCH 08/23] sphinx-apidoc first pass --- doc/source/conf.py | 18 +++-- doc/source/index.rst | 41 +++++++++++- doc/source/modules/orbit.aperture.rst | 31 +++++++++ doc/source/modules/orbit.bumps.rst | 31 +++++++++ doc/source/modules/orbit.bunch_generators.rst | 19 ++++++ doc/source/modules/orbit.bunch_utils.rst | 25 +++++++ doc/source/modules/orbit.collimation.rst | 25 +++++++ doc/source/modules/orbit.core.rst | 10 +++ doc/source/modules/orbit.diagnostics.rst | 37 +++++++++++ doc/source/modules/orbit.errors.rst | 25 +++++++ doc/source/modules/orbit.fieldtracker.rst | 25 +++++++ doc/source/modules/orbit.foils.rst | 25 +++++++ doc/source/modules/orbit.impedances.rst | 25 +++++++ doc/source/modules/orbit.injection.rst | 43 ++++++++++++ doc/source/modules/orbit.kickernodes.rst | 37 +++++++++++ doc/source/modules/orbit.lattice.rst | 37 +++++++++++ doc/source/modules/orbit.matching.rst | 19 ++++++ doc/source/modules/orbit.matrix_lattice.rst | 25 +++++++ doc/source/modules/orbit.orbit_correction.rst | 19 ++++++ doc/source/modules/orbit.parsers.rst | 37 +++++++++++ doc/source/modules/orbit.py_linac.errors.rst | 19 ++++++ doc/source/modules/orbit.py_linac.lattice.rst | 61 +++++++++++++++++ .../orbit.py_linac.lattice_modifications.rst | 49 ++++++++++++++ .../modules/orbit.py_linac.linac_parsers.rst | 25 +++++++ .../modules/orbit.py_linac.materials.rst | 19 ++++++ .../orbit.py_linac.orbit_correction.rst | 19 ++++++ .../orbit.py_linac.overlapping_fields.rst | 31 +++++++++ .../orbit.py_linac.rf_field_readers.rst | 25 +++++++ doc/source/modules/orbit.py_linac.rst | 25 +++++++ doc/source/modules/orbit.rf_cavities.rst | 25 +++++++ doc/source/modules/orbit.rst | 42 ++++++++++++ .../orbit.space_charge.directforce2p5d.rst | 25 +++++++ doc/source/modules/orbit.space_charge.rst | 43 ++++++++++++ .../modules/orbit.space_charge.sc1d.rst | 25 +++++++ .../orbit.space_charge.sc2dslicebyslice.rst | 25 +++++++ .../modules/orbit.space_charge.sc2p5d.rst | 25 +++++++ .../modules/orbit.space_charge.sc3d.rst | 25 +++++++ doc/source/modules/orbit.teapot.rst | 25 +++++++ doc/source/modules/orbit.teapot_base.rst | 10 +++ doc/source/modules/orbit.time_dep.rst | 25 +++++++ doc/source/modules/orbit.utils.fitting.rst | 49 ++++++++++++++ .../modules/orbit.utils.orbit_mpi_utils.rst | 37 +++++++++++ doc/source/modules/orbit.utils.rst | 65 +++++++++++++++++++ doc/source/modules/orbit.utils.xml.rst | 19 ++++++ 44 files changed, 1287 insertions(+), 5 deletions(-) create mode 100644 doc/source/modules/orbit.aperture.rst create mode 100644 doc/source/modules/orbit.bumps.rst create mode 100644 doc/source/modules/orbit.bunch_generators.rst create mode 100644 doc/source/modules/orbit.bunch_utils.rst create mode 100644 doc/source/modules/orbit.collimation.rst create mode 100644 doc/source/modules/orbit.core.rst create mode 100644 doc/source/modules/orbit.diagnostics.rst create mode 100644 doc/source/modules/orbit.errors.rst create mode 100644 doc/source/modules/orbit.fieldtracker.rst create mode 100644 doc/source/modules/orbit.foils.rst create mode 100644 doc/source/modules/orbit.impedances.rst create mode 100644 doc/source/modules/orbit.injection.rst create mode 100644 doc/source/modules/orbit.kickernodes.rst create mode 100644 doc/source/modules/orbit.lattice.rst create mode 100644 doc/source/modules/orbit.matching.rst create mode 100644 doc/source/modules/orbit.matrix_lattice.rst create mode 100644 doc/source/modules/orbit.orbit_correction.rst create mode 100644 doc/source/modules/orbit.parsers.rst create mode 100644 doc/source/modules/orbit.py_linac.errors.rst create mode 100644 doc/source/modules/orbit.py_linac.lattice.rst create mode 100644 doc/source/modules/orbit.py_linac.lattice_modifications.rst create mode 100644 doc/source/modules/orbit.py_linac.linac_parsers.rst create mode 100644 doc/source/modules/orbit.py_linac.materials.rst create mode 100644 doc/source/modules/orbit.py_linac.orbit_correction.rst create mode 100644 doc/source/modules/orbit.py_linac.overlapping_fields.rst create mode 100644 doc/source/modules/orbit.py_linac.rf_field_readers.rst create mode 100644 doc/source/modules/orbit.py_linac.rst create mode 100644 doc/source/modules/orbit.rf_cavities.rst create mode 100644 doc/source/modules/orbit.rst create mode 100644 doc/source/modules/orbit.space_charge.directforce2p5d.rst create mode 100644 doc/source/modules/orbit.space_charge.rst create mode 100644 doc/source/modules/orbit.space_charge.sc1d.rst create mode 100644 doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst create mode 100644 doc/source/modules/orbit.space_charge.sc2p5d.rst create mode 100644 doc/source/modules/orbit.space_charge.sc3d.rst create mode 100644 doc/source/modules/orbit.teapot.rst create mode 100644 doc/source/modules/orbit.teapot_base.rst create mode 100644 doc/source/modules/orbit.time_dep.rst create mode 100644 doc/source/modules/orbit.utils.fitting.rst create mode 100644 doc/source/modules/orbit.utils.orbit_mpi_utils.rst create mode 100644 doc/source/modules/orbit.utils.rst create mode 100644 doc/source/modules/orbit.utils.xml.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 83bb65fd..12246764 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,6 +3,12 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +# -- Path setup -------------------------------------------------------------- +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -14,15 +20,19 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] +autosummary_generate = True +napoleon_numpy_docstring = True templates_path = ['_templates'] exclude_patterns = [] - - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' +html_theme = 'furo' html_static_path = ['_static'] +html_show_source_link = True +html_theme_options = { + # 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', +} diff --git a/doc/source/index.rst b/doc/source/index.rst index dfd70787..d16735f7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,5 +13,44 @@ documentation for details. .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Modules + :hidden: + modules/orbit.aperture + modules/orbit.bump + modules/orbit.bunch_generators + modules/orbit.bunch_utils + modules/orbit.collimation + modules/orbit.diagnostics + modules/orbit.errors + modules/orbit.fieldtracker + modules/orbit.foils + modules/orbit.impedances + modules/orbit.injection + modules/orbit.kickernodes + modules/orbit.lattice + modules/orbit.matching + modules/orbit.matrix_lattice + modules/orbit.orbit_correction + modules/orbit.parsers + modules/orbit.py_linac.errors + modules/orbit.py_linac.lattice + modules/orbit.py_linac.lattice_modifications + modules/orbit.py_linac.linac_parsers + modules/orbit.py_linac.materials + modules/orbit.py_linac.orbit_correction + modules/orbit.py_linac.overlapping_fields + modules/orbit.py_linac.rf_field_readers + modules/orbit.py_linac + modules/orbit.rf_cavities + modules/orbit.space_charge.directforce2p5d + modules/orbit.space_charge + modules/orbit.space_charge.sc1d + modules/orbit.space_charge.sc2dslicebyslice + modules/orbit.space_charge.sc2p5d + modules/orbit.space_charge.sc3d + modules/orbit.teapot + modules/orbit.teapot_base + modules/orbit.time_dep + modules/orbit.utils.fitting + modules/orbit.utils.orbit_mpi_utils diff --git a/doc/source/modules/orbit.aperture.rst b/doc/source/modules/orbit.aperture.rst new file mode 100644 index 00000000..9cf8d713 --- /dev/null +++ b/doc/source/modules/orbit.aperture.rst @@ -0,0 +1,31 @@ +orbit.aperture package +====================== + +Submodules +---------- + + +.. automodule:: orbit.aperture.ApertureLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.aperture.ApertureLatticeRangeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.aperture.TeapotApertureNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.aperture + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bumps.rst b/doc/source/modules/orbit.bumps.rst new file mode 100644 index 00000000..639b975e --- /dev/null +++ b/doc/source/modules/orbit.bumps.rst @@ -0,0 +1,31 @@ +orbit.bumps package +=================== + +Submodules +---------- + + +.. automodule:: orbit.bumps.BumpLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bumps.TeapotBumpNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bumps.bumps + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bumps + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bunch_generators.rst b/doc/source/modules/orbit.bunch_generators.rst new file mode 100644 index 00000000..d2aae682 --- /dev/null +++ b/doc/source/modules/orbit.bunch_generators.rst @@ -0,0 +1,19 @@ +orbit.bunch\_generators package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.bunch_generators.distribution_generators + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bunch_generators + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.bunch_utils.rst b/doc/source/modules/orbit.bunch_utils.rst new file mode 100644 index 00000000..35d80b35 --- /dev/null +++ b/doc/source/modules/orbit.bunch_utils.rst @@ -0,0 +1,25 @@ +orbit.bunch\_utils package +========================== + +Submodules +---------- + + +.. automodule:: orbit.bunch_utils.particleidnumber + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.bunch_utils.serialize + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.bunch_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.collimation.rst b/doc/source/modules/orbit.collimation.rst new file mode 100644 index 00000000..b6100fdb --- /dev/null +++ b/doc/source/modules/orbit.collimation.rst @@ -0,0 +1,25 @@ +orbit.collimation package +========================= + +Submodules +---------- + + +.. automodule:: orbit.collimation.TeapotCollimatorNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.collimation.collimationLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.collimation + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.core.rst b/doc/source/modules/orbit.core.rst new file mode 100644 index 00000000..53921b7d --- /dev/null +++ b/doc/source/modules/orbit.core.rst @@ -0,0 +1,10 @@ +orbit.core package +================== + +Module contents +--------------- + +.. automodule:: orbit.core + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.diagnostics.rst b/doc/source/modules/orbit.diagnostics.rst new file mode 100644 index 00000000..454b5406 --- /dev/null +++ b/doc/source/modules/orbit.diagnostics.rst @@ -0,0 +1,37 @@ +orbit.diagnostics package +========================= + +Submodules +---------- + + +.. automodule:: orbit.diagnostics.TeapotDiagnosticsNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.diagnostics + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.diagnosticsLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.diagnostics.profiles + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.diagnostics + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.errors.rst b/doc/source/modules/orbit.errors.rst new file mode 100644 index 00000000..8ff1deb7 --- /dev/null +++ b/doc/source/modules/orbit.errors.rst @@ -0,0 +1,25 @@ +orbit.errors package +==================== + +Submodules +---------- + + +.. automodule:: orbit.errors.ErrorLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.errors.ErrorNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.errors + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.fieldtracker.rst b/doc/source/modules/orbit.fieldtracker.rst new file mode 100644 index 00000000..bba5190f --- /dev/null +++ b/doc/source/modules/orbit.fieldtracker.rst @@ -0,0 +1,25 @@ +orbit.fieldtracker package +========================== + +Submodules +---------- + + +.. automodule:: orbit.fieldtracker.TeapotFieldLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.fieldtracker.TeapotFieldTrackerNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.fieldtracker + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.foils.rst b/doc/source/modules/orbit.foils.rst new file mode 100644 index 00000000..6d1c11b4 --- /dev/null +++ b/doc/source/modules/orbit.foils.rst @@ -0,0 +1,25 @@ +orbit.foils package +=================== + +Submodules +---------- + + +.. automodule:: orbit.foils.TeapotFoilNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.foils.foilLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.foils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.impedances.rst b/doc/source/modules/orbit.impedances.rst new file mode 100644 index 00000000..4c540fb2 --- /dev/null +++ b/doc/source/modules/orbit.impedances.rst @@ -0,0 +1,25 @@ +orbit.impedances package +======================== + +Submodules +---------- + + +.. automodule:: orbit.impedances.ImpedanceLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.impedances.ImpedanceNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.impedances + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.injection.rst b/doc/source/modules/orbit.injection.rst new file mode 100644 index 00000000..f5b4963e --- /dev/null +++ b/doc/source/modules/orbit.injection.rst @@ -0,0 +1,43 @@ +orbit.injection package +======================= + +Submodules +---------- + + +.. automodule:: orbit.injection.InjectionLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.TeapotInjectionNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.distributions + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.injectparticles + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.injection.joho + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.injection + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.kickernodes.rst b/doc/source/modules/orbit.kickernodes.rst new file mode 100644 index 00000000..2b000f0b --- /dev/null +++ b/doc/source/modules/orbit.kickernodes.rst @@ -0,0 +1,37 @@ +orbit.kickernodes package +========================= + +Submodules +---------- + + +.. automodule:: orbit.kickernodes.KickerLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.TeapotKickerNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.kicker + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.kickernodes.waveforms + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.kickernodes + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.lattice.rst b/doc/source/modules/orbit.lattice.rst new file mode 100644 index 00000000..68ed9568 --- /dev/null +++ b/doc/source/modules/orbit.lattice.rst @@ -0,0 +1,37 @@ +orbit.lattice package +===================== + +Submodules +---------- + + +.. automodule:: orbit.lattice.AccActionsContainer + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccLattice + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.lattice.AccNodeBunchTracker + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.matching.rst b/doc/source/modules/orbit.matching.rst new file mode 100644 index 00000000..020f4937 --- /dev/null +++ b/doc/source/modules/orbit.matching.rst @@ -0,0 +1,19 @@ +orbit.matching package +====================== + +Submodules +---------- + + +.. automodule:: orbit.matching.matching + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.matching + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.matrix_lattice.rst b/doc/source/modules/orbit.matrix_lattice.rst new file mode 100644 index 00000000..b88fc3c4 --- /dev/null +++ b/doc/source/modules/orbit.matrix_lattice.rst @@ -0,0 +1,25 @@ +orbit.matrix\_lattice package +============================= + +Submodules +---------- + + +.. automodule:: orbit.matrix_lattice.BaseMATRIX + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.matrix_lattice.MATRIX_Lattice + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.matrix_lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.orbit_correction.rst b/doc/source/modules/orbit.orbit_correction.rst new file mode 100644 index 00000000..87d458d1 --- /dev/null +++ b/doc/source/modules/orbit.orbit_correction.rst @@ -0,0 +1,19 @@ +orbit.orbit\_correction package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.orbit_correction.orbit_correction + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.orbit_correction + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.parsers.rst b/doc/source/modules/orbit.parsers.rst new file mode 100644 index 00000000..8fffb512 --- /dev/null +++ b/doc/source/modules/orbit.parsers.rst @@ -0,0 +1,37 @@ +orbit.parsers package +===================== + +Submodules +---------- + + +.. automodule:: orbit.parsers.field_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.mad_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.madx_parser + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.parsers.sad_parser + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.parsers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.errors.rst b/doc/source/modules/orbit.py_linac.errors.rst new file mode 100644 index 00000000..304668e5 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.errors.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.errors package +============================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.errors.ErrorNodesAndControllersLib + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.errors + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice.rst b/doc/source/modules/orbit.py_linac.lattice.rst new file mode 100644 index 00000000..08f273fb --- /dev/null +++ b/doc/source/modules/orbit.py_linac.lattice.rst @@ -0,0 +1,61 @@ +orbit.py\_linac.lattice package +=============================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.lattice.LinacAccLatticeFunc + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacAccLatticeLib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacApertureNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacDiagnosticsNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacFieldOverlappingNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacRfGapNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice.LinacTransportMatrixGenNodes + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.lattice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice_modifications.rst b/doc/source/modules/orbit.py_linac.lattice_modifications.rst new file mode 100644 index 00000000..a04b7547 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.lattice_modifications.rst @@ -0,0 +1,49 @@ +orbit.py\_linac.lattice\_modifications package +============================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.lattice_modifications.apertures_additions_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.errors_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.quad_overlap_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.rf_models_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.rf_quad_overlap_modifications_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.lattice_modifications.sns_aperture_additions + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.lattice_modifications + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.linac_parsers.rst b/doc/source/modules/orbit.py_linac.linac_parsers.rst new file mode 100644 index 00000000..32e83a62 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.linac_parsers.rst @@ -0,0 +1,25 @@ +orbit.py\_linac.linac\_parsers package +====================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.linac_parsers.jparc_linac_lattice_factory + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.linac_parsers.sns_linac_lattice_factory + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.linac_parsers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.materials.rst b/doc/source/modules/orbit.py_linac.materials.rst new file mode 100644 index 00000000..f777efb7 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.materials.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.materials package +================================= + +Submodules +---------- + + +.. automodule:: orbit.py_linac.materials.VacuumWindowLinacNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.materials + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.orbit_correction.rst b/doc/source/modules/orbit.py_linac.orbit_correction.rst new file mode 100644 index 00000000..1ef126e2 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.orbit_correction.rst @@ -0,0 +1,19 @@ +orbit.py\_linac.orbit\_correction package +========================================= + +Submodules +---------- + + +.. automodule:: orbit.py_linac.orbit_correction.transport_lines_orbit_correction + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.orbit_correction + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.overlapping_fields.rst b/doc/source/modules/orbit.py_linac.overlapping_fields.rst new file mode 100644 index 00000000..9792294c --- /dev/null +++ b/doc/source/modules/orbit.py_linac.overlapping_fields.rst @@ -0,0 +1,31 @@ +orbit.py\_linac.overlapping\_fields package +=========================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.overlapping_fields.jparc_enge_func_factory + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.overlapping_fields.overlapping_quad_fields_lib + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.overlapping_fields.sns_enge_func_factory + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.overlapping_fields + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rf_field_readers.rst b/doc/source/modules/orbit.py_linac.rf_field_readers.rst new file mode 100644 index 00000000..1e48280c --- /dev/null +++ b/doc/source/modules/orbit.py_linac.rf_field_readers.rst @@ -0,0 +1,25 @@ +orbit.py\_linac.rf\_field\_readers package +========================================== + +Submodules +---------- + + +.. automodule:: orbit.py_linac.rf_field_readers.RF_AxisFieldAnalysis + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.py_linac.rf_field_readers.SuperFish_3D_RF_FieldReader + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.py_linac.rf_field_readers + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rst b/doc/source/modules/orbit.py_linac.rst new file mode 100644 index 00000000..2678c9f4 --- /dev/null +++ b/doc/source/modules/orbit.py_linac.rst @@ -0,0 +1,25 @@ +orbit.py\_linac package +======================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.py_linac.errors + orbit.py_linac.lattice + orbit.py_linac.lattice_modifications + orbit.py_linac.linac_parsers + orbit.py_linac.materials + orbit.py_linac.orbit_correction + orbit.py_linac.overlapping_fields + orbit.py_linac.rf_field_readers + +Module contents +--------------- + +.. automodule:: orbit.py_linac + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.rf_cavities.rst b/doc/source/modules/orbit.rf_cavities.rst new file mode 100644 index 00000000..c41364a8 --- /dev/null +++ b/doc/source/modules/orbit.rf_cavities.rst @@ -0,0 +1,25 @@ +orbit.rf\_cavities package +========================== + +Submodules +---------- + + +.. automodule:: orbit.rf_cavities.RFLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.rf_cavities.RFNode + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.rf_cavities + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.rst b/doc/source/modules/orbit.rst new file mode 100644 index 00000000..baa4ca2e --- /dev/null +++ b/doc/source/modules/orbit.rst @@ -0,0 +1,42 @@ +orbit package +============= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.aperture + orbit.bumps + orbit.bunch_generators + orbit.bunch_utils + orbit.collimation + orbit.core + orbit.diagnostics + orbit.errors + orbit.fieldtracker + orbit.foils + orbit.impedances + orbit.injection + orbit.kickernodes + orbit.lattice + orbit.matching + orbit.matrix_lattice + orbit.orbit_correction + orbit.parsers + orbit.py_linac + orbit.rf_cavities + orbit.space_charge + orbit.teapot + orbit.teapot_base + orbit.time_dep + orbit.utils + +Module contents +--------------- + +.. automodule:: orbit + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.directforce2p5d.rst b/doc/source/modules/orbit.space_charge.directforce2p5d.rst new file mode 100644 index 00000000..fd68e4b0 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.directforce2p5d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.directforce2p5d package +=========================================== + +Submodules +---------- + + +.. automodule:: orbit.space_charge.directforce2p5d.directforceAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.directforce2p5d.directforceLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.directforce2p5d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.rst b/doc/source/modules/orbit.space_charge.rst new file mode 100644 index 00000000..1e6c9931 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.rst @@ -0,0 +1,43 @@ +orbit.space\_charge package +=========================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.space_charge.directforce2p5d + orbit.space_charge.sc1d + orbit.space_charge.sc2dslicebyslice + orbit.space_charge.sc2p5d + orbit.space_charge.sc3d + +Submodules +---------- + + +.. automodule:: orbit.space_charge.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sccenteredLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc1d.rst b/doc/source/modules/orbit.space_charge.sc1d.rst new file mode 100644 index 00000000..fc98d94d --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc1d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc1d package +================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc1d.sc1DNode + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc1d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc1d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst new file mode 100644 index 00000000..b20b40a6 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc2dslicebyslice package +============================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc2dslicebyslice.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc2dslicebyslice.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc2dslicebyslice + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2p5d.rst b/doc/source/modules/orbit.space_charge.sc2p5d.rst new file mode 100644 index 00000000..50c704d3 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc2p5d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc2p5d package +================================== + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc2p5d.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc2p5d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc2p5d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc3d.rst b/doc/source/modules/orbit.space_charge.sc3d.rst new file mode 100644 index 00000000..35c82bf1 --- /dev/null +++ b/doc/source/modules/orbit.space_charge.sc3d.rst @@ -0,0 +1,25 @@ +orbit.space\_charge.sc3d package +================================ + +Submodules +---------- + + +.. automodule:: orbit.space_charge.sc3d.scAccNodes + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.space_charge.sc3d.scLatticeModifications + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.space_charge.sc3d + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.teapot.rst b/doc/source/modules/orbit.teapot.rst new file mode 100644 index 00000000..f924de25 --- /dev/null +++ b/doc/source/modules/orbit.teapot.rst @@ -0,0 +1,25 @@ +orbit.teapot package +==================== + +Submodules +---------- + + +.. automodule:: orbit.teapot.teapot + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.teapot.teapot_matrix_lattice + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.teapot + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.teapot_base.rst b/doc/source/modules/orbit.teapot_base.rst new file mode 100644 index 00000000..97eed985 --- /dev/null +++ b/doc/source/modules/orbit.teapot_base.rst @@ -0,0 +1,10 @@ +orbit.teapot\_base package +========================== + +Module contents +--------------- + +.. automodule:: orbit.teapot_base + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.time_dep.rst b/doc/source/modules/orbit.time_dep.rst new file mode 100644 index 00000000..88c59ecb --- /dev/null +++ b/doc/source/modules/orbit.time_dep.rst @@ -0,0 +1,25 @@ +orbit.time\_dep package +======================= + +Submodules +---------- + + +.. automodule:: orbit.time_dep.time_dep + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.time_dep.waveform + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.time_dep + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.fitting.rst b/doc/source/modules/orbit.utils.fitting.rst new file mode 100644 index 00000000..f1cf43ac --- /dev/null +++ b/doc/source/modules/orbit.utils.fitting.rst @@ -0,0 +1,49 @@ +orbit.utils.fitting package +=========================== + +Submodules +---------- + + +.. automodule:: orbit.utils.fitting.BisectionSearch1D + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.GoldenSectionSearch1D + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.PolynomialFit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.RandomSearch + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.SimplexSearch + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.fitting.Solver_lib + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.fitting + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst new file mode 100644 index 00000000..9ac256d8 --- /dev/null +++ b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst @@ -0,0 +1,37 @@ +orbit.utils.orbit\_mpi\_utils package +===================================== + +Submodules +---------- + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit_nHarm + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit_nHarm + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.orbit_mpi_utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.rst b/doc/source/modules/orbit.utils.rst new file mode 100644 index 00000000..968b26d9 --- /dev/null +++ b/doc/source/modules/orbit.utils.rst @@ -0,0 +1,65 @@ +orbit.utils package +=================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + orbit.utils.fitting + orbit.utils.orbit_mpi_utils + orbit.utils.xml + +Submodules +---------- + + +.. automodule:: orbit.utils.NamedObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.ParamsDictObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.TypedObject + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.consts + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.multiDimArray + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.orbitFinalize + :members: + :show-inheritance: + :undoc-members: + + +.. automodule:: orbit.utils.phaseOperations + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils + :members: + :show-inheritance: + :undoc-members: diff --git a/doc/source/modules/orbit.utils.xml.rst b/doc/source/modules/orbit.utils.xml.rst new file mode 100644 index 00000000..f1ceb913 --- /dev/null +++ b/doc/source/modules/orbit.utils.xml.rst @@ -0,0 +1,19 @@ +orbit.utils.xml package +======================= + +Submodules +---------- + + +.. automodule:: orbit.utils.xml.XmlDataAdaptor + :members: + :show-inheritance: + :undoc-members: + +Module contents +--------------- + +.. automodule:: orbit.utils.xml + :members: + :show-inheritance: + :undoc-members: From c00785919d8cdf7c053e5996707dd9307954115a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 16 Dec 2025 12:39:59 -0500 Subject: [PATCH 09/23] autosummary working. Mostly. --- .gitignore | 1 + doc/source/conf.py | 6 +- doc/source/index.rst | 57 ++---- doc/source/install.rst | 193 ++++++++++++++++++ doc/source/{modules/orbit.rst => modules.rst} | 23 +-- doc/source/modules/orbit.aperture.rst | 31 --- doc/source/modules/orbit.bumps.rst | 31 --- doc/source/modules/orbit.bunch_generators.rst | 19 -- doc/source/modules/orbit.bunch_utils.rst | 25 --- doc/source/modules/orbit.collimation.rst | 25 --- doc/source/modules/orbit.core.rst | 10 - doc/source/modules/orbit.diagnostics.rst | 37 ---- doc/source/modules/orbit.errors.rst | 25 --- doc/source/modules/orbit.fieldtracker.rst | 25 --- doc/source/modules/orbit.foils.rst | 25 --- doc/source/modules/orbit.impedances.rst | 25 --- doc/source/modules/orbit.injection.rst | 43 ---- doc/source/modules/orbit.kickernodes.rst | 37 ---- doc/source/modules/orbit.lattice.rst | 37 ---- doc/source/modules/orbit.matching.rst | 19 -- doc/source/modules/orbit.matrix_lattice.rst | 25 --- doc/source/modules/orbit.orbit_correction.rst | 19 -- doc/source/modules/orbit.parsers.rst | 37 ---- doc/source/modules/orbit.py_linac.errors.rst | 19 -- doc/source/modules/orbit.py_linac.lattice.rst | 61 ------ .../orbit.py_linac.lattice_modifications.rst | 49 ----- .../modules/orbit.py_linac.linac_parsers.rst | 25 --- .../modules/orbit.py_linac.materials.rst | 19 -- .../orbit.py_linac.orbit_correction.rst | 19 -- .../orbit.py_linac.overlapping_fields.rst | 31 --- .../orbit.py_linac.rf_field_readers.rst | 25 --- doc/source/modules/orbit.py_linac.rst | 25 --- doc/source/modules/orbit.rf_cavities.rst | 25 --- .../orbit.space_charge.directforce2p5d.rst | 25 --- doc/source/modules/orbit.space_charge.rst | 43 ---- .../modules/orbit.space_charge.sc1d.rst | 25 --- .../orbit.space_charge.sc2dslicebyslice.rst | 25 --- .../modules/orbit.space_charge.sc2p5d.rst | 25 --- .../modules/orbit.space_charge.sc3d.rst | 25 --- doc/source/modules/orbit.teapot.rst | 25 --- doc/source/modules/orbit.teapot_base.rst | 10 - doc/source/modules/orbit.time_dep.rst | 25 --- doc/source/modules/orbit.utils.fitting.rst | 49 ----- .../modules/orbit.utils.orbit_mpi_utils.rst | 37 ---- doc/source/modules/orbit.utils.rst | 65 ------ doc/source/modules/orbit.utils.xml.rst | 19 -- 46 files changed, 218 insertions(+), 1253 deletions(-) create mode 100644 doc/source/install.rst rename doc/source/{modules/orbit.rst => modules.rst} (73%) delete mode 100644 doc/source/modules/orbit.aperture.rst delete mode 100644 doc/source/modules/orbit.bumps.rst delete mode 100644 doc/source/modules/orbit.bunch_generators.rst delete mode 100644 doc/source/modules/orbit.bunch_utils.rst delete mode 100644 doc/source/modules/orbit.collimation.rst delete mode 100644 doc/source/modules/orbit.core.rst delete mode 100644 doc/source/modules/orbit.diagnostics.rst delete mode 100644 doc/source/modules/orbit.errors.rst delete mode 100644 doc/source/modules/orbit.fieldtracker.rst delete mode 100644 doc/source/modules/orbit.foils.rst delete mode 100644 doc/source/modules/orbit.impedances.rst delete mode 100644 doc/source/modules/orbit.injection.rst delete mode 100644 doc/source/modules/orbit.kickernodes.rst delete mode 100644 doc/source/modules/orbit.lattice.rst delete mode 100644 doc/source/modules/orbit.matching.rst delete mode 100644 doc/source/modules/orbit.matrix_lattice.rst delete mode 100644 doc/source/modules/orbit.orbit_correction.rst delete mode 100644 doc/source/modules/orbit.parsers.rst delete mode 100644 doc/source/modules/orbit.py_linac.errors.rst delete mode 100644 doc/source/modules/orbit.py_linac.lattice.rst delete mode 100644 doc/source/modules/orbit.py_linac.lattice_modifications.rst delete mode 100644 doc/source/modules/orbit.py_linac.linac_parsers.rst delete mode 100644 doc/source/modules/orbit.py_linac.materials.rst delete mode 100644 doc/source/modules/orbit.py_linac.orbit_correction.rst delete mode 100644 doc/source/modules/orbit.py_linac.overlapping_fields.rst delete mode 100644 doc/source/modules/orbit.py_linac.rf_field_readers.rst delete mode 100644 doc/source/modules/orbit.py_linac.rst delete mode 100644 doc/source/modules/orbit.rf_cavities.rst delete mode 100644 doc/source/modules/orbit.space_charge.directforce2p5d.rst delete mode 100644 doc/source/modules/orbit.space_charge.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc1d.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc2p5d.rst delete mode 100644 doc/source/modules/orbit.space_charge.sc3d.rst delete mode 100644 doc/source/modules/orbit.teapot.rst delete mode 100644 doc/source/modules/orbit.teapot_base.rst delete mode 100644 doc/source/modules/orbit.time_dep.rst delete mode 100644 doc/source/modules/orbit.utils.fitting.rst delete mode 100644 doc/source/modules/orbit.utils.orbit_mpi_utils.rst delete mode 100644 doc/source/modules/orbit.utils.rst delete mode 100644 doc/source/modules/orbit.utils.xml.rst diff --git a/.gitignore b/.gitignore index 44b61695..cddf9522 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ PyORBIT.egg-info .*.swp .eggs .venv +_autosummary/ diff --git a/doc/source/conf.py b/doc/source/conf.py index 12246764..ee878d1c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,8 +21,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] -autosummary_generate = True napoleon_numpy_docstring = True +autosummary_imported_members = True templates_path = ['_templates'] exclude_patterns = [] @@ -30,9 +30,9 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'furo' +html_theme = 'pydata_sphinx_theme' html_static_path = ['_static'] html_show_source_link = True html_theme_options = { - # 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', + 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', } diff --git a/doc/source/index.rst b/doc/source/index.rst index d16735f7..08e066b4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,54 +3,23 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -PyORBIT3 documentation -====================== +PyORBIT3 +======== -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + install .. toctree:: :maxdepth: 2 :caption: Modules - :hidden: - modules/orbit.aperture - modules/orbit.bump - modules/orbit.bunch_generators - modules/orbit.bunch_utils - modules/orbit.collimation - modules/orbit.diagnostics - modules/orbit.errors - modules/orbit.fieldtracker - modules/orbit.foils - modules/orbit.impedances - modules/orbit.injection - modules/orbit.kickernodes - modules/orbit.lattice - modules/orbit.matching - modules/orbit.matrix_lattice - modules/orbit.orbit_correction - modules/orbit.parsers - modules/orbit.py_linac.errors - modules/orbit.py_linac.lattice - modules/orbit.py_linac.lattice_modifications - modules/orbit.py_linac.linac_parsers - modules/orbit.py_linac.materials - modules/orbit.py_linac.orbit_correction - modules/orbit.py_linac.overlapping_fields - modules/orbit.py_linac.rf_field_readers - modules/orbit.py_linac - modules/orbit.rf_cavities - modules/orbit.space_charge.directforce2p5d - modules/orbit.space_charge - modules/orbit.space_charge.sc1d - modules/orbit.space_charge.sc2dslicebyslice - modules/orbit.space_charge.sc2p5d - modules/orbit.space_charge.sc3d - modules/orbit.teapot - modules/orbit.teapot_base - modules/orbit.time_dep - modules/orbit.utils.fitting - modules/orbit.utils.orbit_mpi_utils + modules + +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 00000000..a8978c20 --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,193 @@ +Installation +============================= + +1. Introduction +--------------- + +This guide provides instructions how to install PyORBIT code. This guide +doesn’t cover MPI enabled installation. The following configurations are +included in CI testing, versions will change as the runner images +progress. + ++------------+-----------+------------+-------+-----------+-----------+ +| HW | Arc | OS | P | Compiler | Package | +| | hitecture | | ython | | | ++============+===========+============+=======+===========+===========+ +| PC | x86_64 | CentOS | 3 | g | pip-24.0 | +| | | latest | .9.18 | cc-11.4.1 | | ++------------+-----------+------------+-------+-----------+-----------+ +| PC | x86_64 | Ubuntu | 3 | g | pip-24.0 | +| | | latest | .12.3 | cc-13.2.0 | | ++------------+-----------+------------+-------+-----------+-----------+ +| Apple | arm64 | macOS 14 | 3 | cla | pip-24.0 | +| Silicon | | | .12.3 | ng-15.0.0 | | ++------------+-----------+------------+-------+-----------+-----------+ +| PC | x86_64 | Ubuntu | 3. | g | con | +| | | latest | 10.14 | cc-13.2.0 | da-24.5.0 | ++------------+-----------+------------+-------+-----------+-----------+ + +2. Installation from source +--------------------------- + +First step is to clone the source code: + +.. code:: bash + + git clone https://github.com/PyORBIT-Collaboration/PyORBIT3.git + +Pip Setup +~~~~~~~~~ + +**PIP** based setup is more involved, we recommend using **conda** if +unsure. #### Prepare OS The following commands may require root access. + +.. raw:: html + +
+ +.. raw:: html + + + +Click for Ubuntu-based distributions + +.. raw:: html + + + +.. code:: bash + + apt-get update + apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + + + +Click for Redhat-based distributions + +.. raw:: html + + + +.. code:: bash + + dnf group install -y "Development Tools" + dnf install -y python3-devel fftw3-devel + +.. raw:: html + +
+ +.. raw:: html + +
+ +.. raw:: html + + + +Click for Mac + +.. raw:: html + + + +Install Homebrew, make sure that homebrew programs are in the **$PATH** +(optional step in Homebrew installation) +``bash brew install pkg-config fftw`` + +.. raw:: html + +
+ +#### Create Python virtual environment Make sure that you have the +correct python version installed. We require python>3.9. Create virtual +environment. +``python3 -m venv .po3 . .po3/bin/activate pip install -U pip pip install -r requirements.txt pip install -U setuptools`` + +Conda Setup +~~~~~~~~~~~ + +First of all make sure you have conda installed and development +packages. Development packages for Ubuntu: + +:: + + apt update -y + apt install -y curl gpg git build-essential + +Then run the following: + +.. code:: bash + + cd pyorbit3 + conda env create -n po3 --file environment.yml + conda activate po3 + pip install -U meson-python setuptools setuptools-scm + +3. Build +-------- + +If you plan to modify PyORBIT’s code, install it in editable mode. You +will NOT need to rebuild after modifications to the code. +`Meson `__ will rebuild as necessary on import. + +:: + + pip install --no-build-isolation --editable . + +Alternatively if you don’t plan to modify PyORBIT’s code + +:: + + pip install . + +4. Run full SNS linac example +----------------------------- + +Navigate to your **examples** directory and launch tracking of SNS +linac. + +.. code:: bash + + cd examples/SNS_Linac/pyorbit3_linac_model/ + python pyorbit3_sns_linac_mebt_hebt2.py + +5. MPI consideration +-------------------- + +By default, the build system will try to find MPI and compile against +it. You can control which MPI to use with command line option when +building. + +.. code:: bash + + pip install --config-settings=setup-args="-DUSE_MPI=none" . + +Above will build PyORBIT without MPI even if MPI is present. You can +change that option to ``mpich``, ``ompi``, ``none`` or ``auto`` +(default). \| MPI flavor \| Installation command \| \|—————\|————–\| \| +No MPI \| +``pip install --config-settings=setup-args="-DUSE_MPI=none" .`` \| \| +The first found MPI installation if any \| +``pip install --config-settings=setup-args="-DUSE_MPI=auto" .`` \| \| +OpenMPI \| +``pip install --config-settings=setup-args="-DUSE_MPI=ompi" .`` \| \| +MPICH \| +``pip install --config-settings=setup-args="-DUSE_MPI=mpich" .`` \| + +Meson uses PKG_CONFIG to discover packages. It could be useful to help +it to find your MPI installation: + +.. code:: bash + + PKG_CONFIG_PATH=/opt/lib/pkgconfig pip install --verbose . diff --git a/doc/source/modules/orbit.rst b/doc/source/modules.rst similarity index 73% rename from doc/source/modules/orbit.rst rename to doc/source/modules.rst index baa4ca2e..1251b4e0 100644 --- a/doc/source/modules/orbit.rst +++ b/doc/source/modules.rst @@ -1,11 +1,12 @@ -orbit package -============= - -Subpackages ------------ - +Modules +======= .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :caption: Modules + +.. autosummary:: + :toctree: _autosummary + :recursive: orbit.aperture orbit.bumps @@ -32,11 +33,3 @@ Subpackages orbit.teapot_base orbit.time_dep orbit.utils - -Module contents ---------------- - -.. automodule:: orbit - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.aperture.rst b/doc/source/modules/orbit.aperture.rst deleted file mode 100644 index 9cf8d713..00000000 --- a/doc/source/modules/orbit.aperture.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.aperture package -====================== - -Submodules ----------- - - -.. automodule:: orbit.aperture.ApertureLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.aperture.ApertureLatticeRangeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.aperture.TeapotApertureNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.aperture - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bumps.rst b/doc/source/modules/orbit.bumps.rst deleted file mode 100644 index 639b975e..00000000 --- a/doc/source/modules/orbit.bumps.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.bumps package -=================== - -Submodules ----------- - - -.. automodule:: orbit.bumps.BumpLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bumps.TeapotBumpNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bumps.bumps - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bumps - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bunch_generators.rst b/doc/source/modules/orbit.bunch_generators.rst deleted file mode 100644 index d2aae682..00000000 --- a/doc/source/modules/orbit.bunch_generators.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.bunch\_generators package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.bunch_generators.distribution_generators - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bunch_generators - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.bunch_utils.rst b/doc/source/modules/orbit.bunch_utils.rst deleted file mode 100644 index 35d80b35..00000000 --- a/doc/source/modules/orbit.bunch_utils.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.bunch\_utils package -========================== - -Submodules ----------- - - -.. automodule:: orbit.bunch_utils.particleidnumber - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.bunch_utils.serialize - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.bunch_utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.collimation.rst b/doc/source/modules/orbit.collimation.rst deleted file mode 100644 index b6100fdb..00000000 --- a/doc/source/modules/orbit.collimation.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.collimation package -========================= - -Submodules ----------- - - -.. automodule:: orbit.collimation.TeapotCollimatorNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.collimation.collimationLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.collimation - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.core.rst b/doc/source/modules/orbit.core.rst deleted file mode 100644 index 53921b7d..00000000 --- a/doc/source/modules/orbit.core.rst +++ /dev/null @@ -1,10 +0,0 @@ -orbit.core package -================== - -Module contents ---------------- - -.. automodule:: orbit.core - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.diagnostics.rst b/doc/source/modules/orbit.diagnostics.rst deleted file mode 100644 index 454b5406..00000000 --- a/doc/source/modules/orbit.diagnostics.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.diagnostics package -========================= - -Submodules ----------- - - -.. automodule:: orbit.diagnostics.TeapotDiagnosticsNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.diagnostics - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.diagnosticsLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.diagnostics.profiles - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.diagnostics - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.errors.rst b/doc/source/modules/orbit.errors.rst deleted file mode 100644 index 8ff1deb7..00000000 --- a/doc/source/modules/orbit.errors.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.errors package -==================== - -Submodules ----------- - - -.. automodule:: orbit.errors.ErrorLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.errors.ErrorNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.errors - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.fieldtracker.rst b/doc/source/modules/orbit.fieldtracker.rst deleted file mode 100644 index bba5190f..00000000 --- a/doc/source/modules/orbit.fieldtracker.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.fieldtracker package -========================== - -Submodules ----------- - - -.. automodule:: orbit.fieldtracker.TeapotFieldLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.fieldtracker.TeapotFieldTrackerNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.fieldtracker - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.foils.rst b/doc/source/modules/orbit.foils.rst deleted file mode 100644 index 6d1c11b4..00000000 --- a/doc/source/modules/orbit.foils.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.foils package -=================== - -Submodules ----------- - - -.. automodule:: orbit.foils.TeapotFoilNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.foils.foilLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.foils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.impedances.rst b/doc/source/modules/orbit.impedances.rst deleted file mode 100644 index 4c540fb2..00000000 --- a/doc/source/modules/orbit.impedances.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.impedances package -======================== - -Submodules ----------- - - -.. automodule:: orbit.impedances.ImpedanceLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.impedances.ImpedanceNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.impedances - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.injection.rst b/doc/source/modules/orbit.injection.rst deleted file mode 100644 index f5b4963e..00000000 --- a/doc/source/modules/orbit.injection.rst +++ /dev/null @@ -1,43 +0,0 @@ -orbit.injection package -======================= - -Submodules ----------- - - -.. automodule:: orbit.injection.InjectionLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.TeapotInjectionNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.distributions - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.injectparticles - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.injection.joho - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.injection - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.kickernodes.rst b/doc/source/modules/orbit.kickernodes.rst deleted file mode 100644 index 2b000f0b..00000000 --- a/doc/source/modules/orbit.kickernodes.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.kickernodes package -========================= - -Submodules ----------- - - -.. automodule:: orbit.kickernodes.KickerLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.TeapotKickerNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.kicker - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.kickernodes.waveforms - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.kickernodes - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.lattice.rst b/doc/source/modules/orbit.lattice.rst deleted file mode 100644 index 68ed9568..00000000 --- a/doc/source/modules/orbit.lattice.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.lattice package -===================== - -Submodules ----------- - - -.. automodule:: orbit.lattice.AccActionsContainer - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccLattice - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.lattice.AccNodeBunchTracker - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.matching.rst b/doc/source/modules/orbit.matching.rst deleted file mode 100644 index 020f4937..00000000 --- a/doc/source/modules/orbit.matching.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.matching package -====================== - -Submodules ----------- - - -.. automodule:: orbit.matching.matching - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.matching - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.matrix_lattice.rst b/doc/source/modules/orbit.matrix_lattice.rst deleted file mode 100644 index b88fc3c4..00000000 --- a/doc/source/modules/orbit.matrix_lattice.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.matrix\_lattice package -============================= - -Submodules ----------- - - -.. automodule:: orbit.matrix_lattice.BaseMATRIX - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.matrix_lattice.MATRIX_Lattice - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.matrix_lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.orbit_correction.rst b/doc/source/modules/orbit.orbit_correction.rst deleted file mode 100644 index 87d458d1..00000000 --- a/doc/source/modules/orbit.orbit_correction.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.orbit\_correction package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.orbit_correction.orbit_correction - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.orbit_correction - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.parsers.rst b/doc/source/modules/orbit.parsers.rst deleted file mode 100644 index 8fffb512..00000000 --- a/doc/source/modules/orbit.parsers.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.parsers package -===================== - -Submodules ----------- - - -.. automodule:: orbit.parsers.field_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.mad_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.madx_parser - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.parsers.sad_parser - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.parsers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.errors.rst b/doc/source/modules/orbit.py_linac.errors.rst deleted file mode 100644 index 304668e5..00000000 --- a/doc/source/modules/orbit.py_linac.errors.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.errors package -============================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.errors.ErrorNodesAndControllersLib - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.errors - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice.rst b/doc/source/modules/orbit.py_linac.lattice.rst deleted file mode 100644 index 08f273fb..00000000 --- a/doc/source/modules/orbit.py_linac.lattice.rst +++ /dev/null @@ -1,61 +0,0 @@ -orbit.py\_linac.lattice package -=============================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.lattice.LinacAccLatticeFunc - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacAccLatticeLib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacApertureNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacDiagnosticsNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacFieldOverlappingNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacRfGapNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice.LinacTransportMatrixGenNodes - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.lattice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.lattice_modifications.rst b/doc/source/modules/orbit.py_linac.lattice_modifications.rst deleted file mode 100644 index a04b7547..00000000 --- a/doc/source/modules/orbit.py_linac.lattice_modifications.rst +++ /dev/null @@ -1,49 +0,0 @@ -orbit.py\_linac.lattice\_modifications package -============================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.lattice_modifications.apertures_additions_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.errors_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.quad_overlap_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.rf_models_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.rf_quad_overlap_modifications_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.lattice_modifications.sns_aperture_additions - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.lattice_modifications - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.linac_parsers.rst b/doc/source/modules/orbit.py_linac.linac_parsers.rst deleted file mode 100644 index 32e83a62..00000000 --- a/doc/source/modules/orbit.py_linac.linac_parsers.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac.linac\_parsers package -====================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.linac_parsers.jparc_linac_lattice_factory - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.linac_parsers.sns_linac_lattice_factory - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.linac_parsers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.materials.rst b/doc/source/modules/orbit.py_linac.materials.rst deleted file mode 100644 index f777efb7..00000000 --- a/doc/source/modules/orbit.py_linac.materials.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.materials package -================================= - -Submodules ----------- - - -.. automodule:: orbit.py_linac.materials.VacuumWindowLinacNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.materials - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.orbit_correction.rst b/doc/source/modules/orbit.py_linac.orbit_correction.rst deleted file mode 100644 index 1ef126e2..00000000 --- a/doc/source/modules/orbit.py_linac.orbit_correction.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.py\_linac.orbit\_correction package -========================================= - -Submodules ----------- - - -.. automodule:: orbit.py_linac.orbit_correction.transport_lines_orbit_correction - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.orbit_correction - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.overlapping_fields.rst b/doc/source/modules/orbit.py_linac.overlapping_fields.rst deleted file mode 100644 index 9792294c..00000000 --- a/doc/source/modules/orbit.py_linac.overlapping_fields.rst +++ /dev/null @@ -1,31 +0,0 @@ -orbit.py\_linac.overlapping\_fields package -=========================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.overlapping_fields.jparc_enge_func_factory - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.overlapping_fields.overlapping_quad_fields_lib - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.overlapping_fields.sns_enge_func_factory - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.overlapping_fields - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rf_field_readers.rst b/doc/source/modules/orbit.py_linac.rf_field_readers.rst deleted file mode 100644 index 1e48280c..00000000 --- a/doc/source/modules/orbit.py_linac.rf_field_readers.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac.rf\_field\_readers package -========================================== - -Submodules ----------- - - -.. automodule:: orbit.py_linac.rf_field_readers.RF_AxisFieldAnalysis - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.py_linac.rf_field_readers.SuperFish_3D_RF_FieldReader - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.py_linac.rf_field_readers - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.py_linac.rst b/doc/source/modules/orbit.py_linac.rst deleted file mode 100644 index 2678c9f4..00000000 --- a/doc/source/modules/orbit.py_linac.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.py\_linac package -======================= - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.py_linac.errors - orbit.py_linac.lattice - orbit.py_linac.lattice_modifications - orbit.py_linac.linac_parsers - orbit.py_linac.materials - orbit.py_linac.orbit_correction - orbit.py_linac.overlapping_fields - orbit.py_linac.rf_field_readers - -Module contents ---------------- - -.. automodule:: orbit.py_linac - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.rf_cavities.rst b/doc/source/modules/orbit.rf_cavities.rst deleted file mode 100644 index c41364a8..00000000 --- a/doc/source/modules/orbit.rf_cavities.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.rf\_cavities package -========================== - -Submodules ----------- - - -.. automodule:: orbit.rf_cavities.RFLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.rf_cavities.RFNode - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.rf_cavities - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.directforce2p5d.rst b/doc/source/modules/orbit.space_charge.directforce2p5d.rst deleted file mode 100644 index fd68e4b0..00000000 --- a/doc/source/modules/orbit.space_charge.directforce2p5d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.directforce2p5d package -=========================================== - -Submodules ----------- - - -.. automodule:: orbit.space_charge.directforce2p5d.directforceAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.directforce2p5d.directforceLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.directforce2p5d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.rst b/doc/source/modules/orbit.space_charge.rst deleted file mode 100644 index 1e6c9931..00000000 --- a/doc/source/modules/orbit.space_charge.rst +++ /dev/null @@ -1,43 +0,0 @@ -orbit.space\_charge package -=========================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.space_charge.directforce2p5d - orbit.space_charge.sc1d - orbit.space_charge.sc2dslicebyslice - orbit.space_charge.sc2p5d - orbit.space_charge.sc3d - -Submodules ----------- - - -.. automodule:: orbit.space_charge.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sccenteredLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc1d.rst b/doc/source/modules/orbit.space_charge.sc1d.rst deleted file mode 100644 index fc98d94d..00000000 --- a/doc/source/modules/orbit.space_charge.sc1d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc1d package -================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc1d.sc1DNode - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc1d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc1d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst b/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst deleted file mode 100644 index b20b40a6..00000000 --- a/doc/source/modules/orbit.space_charge.sc2dslicebyslice.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc2dslicebyslice package -============================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc2dslicebyslice.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc2dslicebyslice.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc2dslicebyslice - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc2p5d.rst b/doc/source/modules/orbit.space_charge.sc2p5d.rst deleted file mode 100644 index 50c704d3..00000000 --- a/doc/source/modules/orbit.space_charge.sc2p5d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc2p5d package -================================== - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc2p5d.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc2p5d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc2p5d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.space_charge.sc3d.rst b/doc/source/modules/orbit.space_charge.sc3d.rst deleted file mode 100644 index 35c82bf1..00000000 --- a/doc/source/modules/orbit.space_charge.sc3d.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.space\_charge.sc3d package -================================ - -Submodules ----------- - - -.. automodule:: orbit.space_charge.sc3d.scAccNodes - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.space_charge.sc3d.scLatticeModifications - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.space_charge.sc3d - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.teapot.rst b/doc/source/modules/orbit.teapot.rst deleted file mode 100644 index f924de25..00000000 --- a/doc/source/modules/orbit.teapot.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.teapot package -==================== - -Submodules ----------- - - -.. automodule:: orbit.teapot.teapot - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.teapot.teapot_matrix_lattice - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.teapot - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.teapot_base.rst b/doc/source/modules/orbit.teapot_base.rst deleted file mode 100644 index 97eed985..00000000 --- a/doc/source/modules/orbit.teapot_base.rst +++ /dev/null @@ -1,10 +0,0 @@ -orbit.teapot\_base package -========================== - -Module contents ---------------- - -.. automodule:: orbit.teapot_base - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.time_dep.rst b/doc/source/modules/orbit.time_dep.rst deleted file mode 100644 index 88c59ecb..00000000 --- a/doc/source/modules/orbit.time_dep.rst +++ /dev/null @@ -1,25 +0,0 @@ -orbit.time\_dep package -======================= - -Submodules ----------- - - -.. automodule:: orbit.time_dep.time_dep - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.time_dep.waveform - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.time_dep - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.fitting.rst b/doc/source/modules/orbit.utils.fitting.rst deleted file mode 100644 index f1cf43ac..00000000 --- a/doc/source/modules/orbit.utils.fitting.rst +++ /dev/null @@ -1,49 +0,0 @@ -orbit.utils.fitting package -=========================== - -Submodules ----------- - - -.. automodule:: orbit.utils.fitting.BisectionSearch1D - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.GoldenSectionSearch1D - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.PolynomialFit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.RandomSearch - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.SimplexSearch - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.fitting.Solver_lib - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.fitting - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst b/doc/source/modules/orbit.utils.orbit_mpi_utils.rst deleted file mode 100644 index 9ac256d8..00000000 --- a/doc/source/modules/orbit.utils.orbit_mpi_utils.rst +++ /dev/null @@ -1,37 +0,0 @@ -orbit.utils.orbit\_mpi\_utils package -===================================== - -Submodules ----------- - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_orbit_to_pyorbit_nHarm - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbit_mpi_utils.bunch_pyorbit_to_orbit_nHarm - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.orbit_mpi_utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.rst b/doc/source/modules/orbit.utils.rst deleted file mode 100644 index 968b26d9..00000000 --- a/doc/source/modules/orbit.utils.rst +++ /dev/null @@ -1,65 +0,0 @@ -orbit.utils package -=================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - orbit.utils.fitting - orbit.utils.orbit_mpi_utils - orbit.utils.xml - -Submodules ----------- - - -.. automodule:: orbit.utils.NamedObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.ParamsDictObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.TypedObject - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.consts - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.multiDimArray - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.orbitFinalize - :members: - :show-inheritance: - :undoc-members: - - -.. automodule:: orbit.utils.phaseOperations - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils - :members: - :show-inheritance: - :undoc-members: diff --git a/doc/source/modules/orbit.utils.xml.rst b/doc/source/modules/orbit.utils.xml.rst deleted file mode 100644 index f1ceb913..00000000 --- a/doc/source/modules/orbit.utils.xml.rst +++ /dev/null @@ -1,19 +0,0 @@ -orbit.utils.xml package -======================= - -Submodules ----------- - - -.. automodule:: orbit.utils.xml.XmlDataAdaptor - :members: - :show-inheritance: - :undoc-members: - -Module contents ---------------- - -.. automodule:: orbit.utils.xml - :members: - :show-inheritance: - :undoc-members: From 76d5949c26c6fbf0c0751b01020cfb7ed7573b0a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 18 Dec 2025 15:34:36 -0500 Subject: [PATCH 10/23] Doxygen + breathe + exhale --- doc/.gitignore | 2 ++ doc/Makefile | 6 +++++- doc/source/conf.py | 30 +++++++++++++++++++++++++++++- doc/source/index.rst | 6 ++++++ 4 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..ca5796cb --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +_doxygen +source/api diff --git a/doc/Makefile b/doc/Makefile index d0c3cbf1..dc706e6c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,9 +12,13 @@ BUILDDIR = build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile clean # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index ee878d1c..22a6cd8c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -20,13 +20,41 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.coverage', 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon'] +extensions = ['sphinx.ext.coverage', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.napoleon', + 'breathe', + 'exhale'] napoleon_numpy_docstring = True autosummary_imported_members = True templates_path = ['_templates'] exclude_patterns = [] +# -- Breathe and Exhale Options --------------------------------------------------------- +breathe_projects = { + "PyORBIT3": "./_doxygen/xml", + } +breathe_default_project = "PyORBIT3" + +doxyfile = '\n'.join([ + "INPUT = ../../src", + "EXCLUDE_PATTERNS = *wrap*", + ]) + +exhale_args = { + "containmentFolder": "./api", + "rootFileName": "pyorbit_root.rst", + "doxygenStripFromPath": "..", + "rootFileTitle": "PyORBIT3 API", + "createTreeView": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": doxyfile, + } + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/doc/source/index.rst b/doc/source/index.rst index 08e066b4..5c29b916 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,6 +18,12 @@ PyORBIT3 modules +.. toctree:: + :maxdepth: 2 + :caption: C++ Interface + + api/pyorbit_root.rst + Indices and tables ================== * :ref:`genindex` From 6084ddb5978c3f6a94f946898561022f26d0f66a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 18 Dec 2025 15:36:40 -0500 Subject: [PATCH 11/23] Should be api not _api --- doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index dc706e6c..16b56424 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/_api + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 91da60132bcf8fee0edb413c7c69f45eefdbecc6 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Thu, 8 Jan 2026 17:10:42 -0500 Subject: [PATCH 12/23] Remove duplicates in C++ docs Resolved an issue where some of the C++ side of PyORBIT was getting documented twice. Ignored some macros that were causing errors while building documentation. Documentated a couple of methods as examples. --- doc/Makefile | 2 +- doc/source/conf.py | 10 +- doc/source/index.rst | 2 +- doc/source/modules.rst | 11 +- docs-environment.yml | 139 ++++++++++++++++++ src/mpi/orbit_mpi.cc | 2 + .../BunchDiagnostics/BunchTwissAnalysis.cc | 4 - .../BunchDiagnostics/BunchTwissAnalysis.hh | 11 +- src/orbit/MaterialInteractions/numrecipes.cc | 9 +- src/orbit/MaterialInteractions/numrecipes.hh | 49 +++++- .../UniformEllipsoidFieldCalculator.cc | 2 + src/utils/Random.cc | 2 + 12 files changed, 229 insertions(+), 14 deletions(-) create mode 100644 docs-environment.yml diff --git a/doc/Makefile b/doc/Makefile index 16b56424..e5bfb095 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api + rm -rf "$(SOURCEDIR)"/_doxygen "$(SOURCEDIR)"/api "$(SOURCEDIR)"/_autosummary @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py index 22a6cd8c..1a9dc3d4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -5,6 +5,7 @@ # -- Path setup -------------------------------------------------------------- import sys +import pathlib from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) @@ -42,14 +43,16 @@ doxyfile = '\n'.join([ "INPUT = ../../src", - "EXCLUDE_PATTERNS = *wrap*", + "EXCLUDE_PATTERNS = *wrap* *_init.cc", + "PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS", + "PREDEFINED += PyObject_HEAD=\"PyObject ob_base;\"" ]) exhale_args = { "containmentFolder": "./api", "rootFileName": "pyorbit_root.rst", "doxygenStripFromPath": "..", - "rootFileTitle": "PyORBIT3 API", + "rootFileTitle": "PyORBIT3 C++ API", "createTreeView": True, "exhaleExecutesDoxygen": True, "exhaleDoxygenStdin": doxyfile, @@ -63,4 +66,7 @@ html_show_source_link = True html_theme_options = { 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', + 'logo': { + 'text': "PyORBIT3", + } } diff --git a/doc/source/index.rst b/doc/source/index.rst index 5c29b916..7d38cecb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -20,7 +20,7 @@ PyORBIT3 .. toctree:: :maxdepth: 2 - :caption: C++ Interface + :caption: C++ API api/pyorbit_root.rst diff --git a/doc/source/modules.rst b/doc/source/modules.rst index 1251b4e0..d8cb2ccd 100644 --- a/doc/source/modules.rst +++ b/doc/source/modules.rst @@ -5,7 +5,7 @@ Modules :caption: Modules .. autosummary:: - :toctree: _autosummary + :toctree: _autosummary/ :recursive: orbit.aperture @@ -26,7 +26,14 @@ Modules orbit.matrix_lattice orbit.orbit_correction orbit.parsers - orbit.py_linac + orbit.py_linac.errors + orbit.py_linac.lattice + orbit.py_linac.lattice_modifications + orbit.py_linac.linac_parsers + orbit.py_linac.materials + orbit.py_linac.orbit_correction + orbit.py_linac.overlapping_fields + orbit.py_linac.rf_field_readers orbit.rf_cavities orbit.space_charge orbit.teapot diff --git a/docs-environment.yml b/docs-environment.yml new file mode 100644 index 00000000..79a24a96 --- /dev/null +++ b/docs-environment.yml @@ -0,0 +1,139 @@ +name: docs +channels: + - conda-forge +dependencies: + - _openmp_mutex=4.5=7_kmp_llvm + - accessible-pygments=0.0.5=pyhd8ed1ab_1 + - alabaster=0.7.16=pyhd8ed1ab_0 + - babel=2.17.0=pyhd8ed1ab_0 + - backports.zstd=1.2.0=py313hf42fe89_0 + - beautifulsoup4=4.14.3=pyha770c72_0 + - black=25.12.0=pyh866005b_0 + - breathe=4.35.0=pyhd8ed1ab_4 + - brotli=1.2.0=h7d5ae5b_1 + - brotli-bin=1.2.0=hc919400_1 + - brotli-python=1.2.0=py313hde1f3bb_1 + - bzip2=1.0.8=hd037594_8 + - c-ares=1.34.6=hc919400_0 + - ca-certificates=2025.11.12=hbd8a1cb_0 + - certifi=2025.11.12=pyhd8ed1ab_0 + - charset-normalizer=3.4.4=pyhd8ed1ab_0 + - click=8.3.1=pyh8f84b5b_1 + - colorama=0.4.6=pyhd8ed1ab_1 + - contourpy=1.3.3=py313ha61f8ec_3 + - cycler=0.12.1=pyhcf101f3_2 + - docutils=0.17.1=py313h8f79df9_7 + - doxygen=1.13.2=h493aca8_0 + - exhale=0.3.7=pyhd8ed1ab_1 + - fonttools=4.61.1=pyh7db6752_0 + - freetype=2.14.1=hce30654_0 + - h2=4.3.0=pyhcf101f3_0 + - hpack=4.1.0=pyhd8ed1ab_0 + - hyperframe=6.1.0=pyhd8ed1ab_0 + - icu=75.1=hfee45f7_0 + - idna=3.11=pyhd8ed1ab_0 + - imagesize=1.4.1=pyhd8ed1ab_0 + - importlib-metadata=8.7.0=pyhe01879c_1 + - isort=7.0.0=pyhd8ed1ab_0 + - jinja2=3.1.6=pyhcf101f3_1 + - kiwisolver=1.4.9=py313h7add70c_2 + - lcms2=2.17=h7eeda09_0 + - lerc=4.0.0=hd64df32_1 + - libabseil=20250512.1=cxx17_hd41c47c_0 + - libblas=3.11.0=5_h51639a9_openblas + - libbrotlicommon=1.2.0=hc919400_1 + - libbrotlidec=1.2.0=hc919400_1 + - libbrotlienc=1.2.0=hc919400_1 + - libcblas=3.11.0=5_hb0561ab_openblas + - libcxx=21.1.8=hf598326_0 + - libdeflate=1.25=hc11a715_0 + - libev=4.33=h93a5062_2 + - libevent=2.1.12=h2757513_1 + - libexpat=2.7.3=haf25636_0 + - libfabric=2.4.0=hce30654_0 + - libfabric1=2.4.0=hc919400_0 + - libffi=3.5.2=he5f378a_0 + - libfreetype=2.14.1=hce30654_0 + - libfreetype6=2.14.1=h6da58f4_0 + - libgcc=15.2.0=hcbb3090_16 + - libgfortran=15.2.0=h07b0088_16 + - libgfortran5=15.2.0=hdae7583_16 + - libhwloc=2.12.1=default_ha3cc4f2_1003 + - libiconv=1.18=h23cfdf5_2 + - libjpeg-turbo=3.1.2=hc919400_0 + - liblapack=3.11.0=5_hd9741b5_openblas + - liblzma=5.8.1=h39f12f2_2 + - libmpdec=4.0.0=h5505292_0 + - libnghttp2=1.67.0=hc438710_0 + - libopenblas=0.3.30=openmp_ha158390_3 + - libpmix=5.0.8=h3e7ebac_2 + - libpng=1.6.53=hfab5511_0 + - libsqlite=3.51.1=h9a5124b_0 + - libtiff=4.7.1=h4030677_1 + - libuv=1.51.0=h6caf38d_1 + - libwebp-base=1.6.0=h07db88b_0 + - libxcb=1.17.0=hdb1d25a_0 + - libxml2=2.15.1=h9329255_0 + - libxml2-16=2.15.1=h0ff4647_0 + - libxslt=1.1.43=hb2570ba_1 + - libzlib=1.3.1=h8359307_2 + - llvm-openmp=21.1.8=h4a912ad_0 + - lxml=6.0.2=py313he6cafaa_2 + - markupsafe=3.0.3=pyh7db6752_0 + - matplotlib=3.10.8=py313h39782a4_0 + - matplotlib-base=3.10.8=py313h58042b9_0 + - mpi=1.0.1=openmpi + - munkres=1.1.4=pyhd8ed1ab_1 + - mypy_extensions=1.1.0=pyha770c72_0 + - ncurses=6.5=h5e97a16_3 + - nodeenv=1.9.1=pyhd8ed1ab_1 + - nodejs=25.2.1=h5230ea7_1 + - numpy=2.3.5=py313h9771d21_0 + - openjpeg=2.5.4=hbfb3c88_0 + - openmpi=5.0.8=h13a75e3_109 + - openssl=3.6.0=h5503f6c_0 + - packaging=25.0=pyh29332c3_1 + - pathspec=0.12.1=pyhd8ed1ab_1 + - pillow=12.0.0=py313ha86496b_2 + - pip=25.3=pyh145f28c_0 + - platformdirs=4.5.1=pyhcf101f3_0 + - pthread-stubs=0.4=hd74edd7_1002 + - pydata-sphinx-theme=0.13.3=pyhd8ed1ab_0 + - pygments=2.19.2=pyhd8ed1ab_0 + - pyparsing=3.2.5=pyhcf101f3_0 + - pyright=1.1.407=py313h9734d34_0 + - pysocks=1.7.1=pyha55dd90_7 + - python=3.13.11=hfc2f54d_100_cp313 + - python-dateutil=2.9.0.post0=pyhe01879c_2 + - python_abi=3.13=8_cp313 + - pytokens=0.3.0=pyhcf101f3_0 + - pytz=2025.2=pyhd8ed1ab_0 + - qhull=2020.2=h420ef59_5 + - readline=8.3=h46df422_0 + - requests=2.32.5=pyhd8ed1ab_0 + - roman-numerals=4.1.0=pyhd8ed1ab_0 + - scipy=1.16.3=py313h0d10b07_1 + - setuptools=80.9.0=pyhff2d567_0 + - six=1.17.0=pyhe01879c_1 + - snowballstemmer=3.0.1=pyhd8ed1ab_0 + - soupsieve=2.8=pyhd8ed1ab_0 + - sphinx=4.5.0=pyh6c4a22f_0 + - sphinxcontrib-applehelp=1.0.4=pyhd8ed1ab_0 + - sphinxcontrib-devhelp=1.0.2=py_0 + - sphinxcontrib-htmlhelp=2.0.1=pyhd8ed1ab_0 + - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_1 + - sphinxcontrib-qthelp=1.0.3=py_0 + - sphinxcontrib-serializinghtml=1.1.5=pyhd8ed1ab_2 + - standard-imghdr=3.13.0=pyh29332c3_0 + - tk=8.6.13=h892fb3f_3 + - tornado=6.5.4=py313h6535dbc_0 + - typing-extensions=4.15.0=h396c80c_0 + - typing_extensions=4.15.0=pyhcf101f3_0 + - tzdata=2025c=h8577fbf_0 + - unicodedata2=17.0.0=py313h6535dbc_1 + - urllib3=2.6.2=pyhd8ed1ab_0 + - xorg-libxau=1.0.12=hc919400_1 + - xorg-libxdmcp=1.1.5=hc919400_1 + - zipp=3.23.0=pyhcf101f3_1 + - zlib-ng=2.3.2=h248ca61_0 + - zstd=1.5.7=hbf9d68e_6 diff --git a/src/mpi/orbit_mpi.cc b/src/mpi/orbit_mpi.cc index 8a36065e..2dc97e71 100644 --- a/src/mpi/orbit_mpi.cc +++ b/src/mpi/orbit_mpi.cc @@ -5,6 +5,7 @@ #include #include +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) /** A C wrapper around MPI_Init. */ int ORBIT_MPI_Init(){ int res = 0; @@ -620,3 +621,4 @@ int ORBIT_MPI_Get_count(MPI_Status *status, MPI_Datatype datatype, int *count){ #endif return res; } +#endif // !defined(DOXYGEN_SHOULD_SKIP_THIS) diff --git a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc index 2063b6ae..0a361326 100644 --- a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc +++ b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.cc @@ -337,10 +337,6 @@ void BunchTwissAnalysis::computeBunchMoments(Bunch* bunch, int order, int disper } - - - -/** Returns the centered correlation <(x-)*(y-)> = - * */ double BunchTwissAnalysis::getCorrelation(int ic, int jc){ if(ic < 0 || ic > 5 || jc < 0 || jc >5) return 0.; return (corr_arr[ic+6*jc] - avg_arr[ic]* avg_arr[jc]); diff --git a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh index df6e2b4b..deaa20ee 100644 --- a/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh +++ b/src/orbit/BunchDiagnostics/BunchTwissAnalysis.hh @@ -26,7 +26,16 @@ class BunchTwissAnalysis: public OrbitUtils::CppPyWrapper /** Performs the Twiss analysis of the bunch */ void analyzeBunch(Bunch* bunch); - /** Returns the centered correlation <(x-)*(y-)> = - * */ + /** + * @brief Returns the centered correlation between two components. + * + * \f$\langle (x-\langle x\rangle)(y-\langle y\rangle)\rangle + * = \langle x y\rangle - \langle x\rangle\langle y\rangle\f$ + * + * @param ic Index of the first component (x). + * @param jc Index of the second component (y). + * @return The centered correlation value as a double. + */ double getCorrelation(int ic, int jc); /** Returns the average value for coordinate with index ic */ diff --git a/src/orbit/MaterialInteractions/numrecipes.cc b/src/orbit/MaterialInteractions/numrecipes.cc index eadd37ee..a38dd327 100644 --- a/src/orbit/MaterialInteractions/numrecipes.cc +++ b/src/orbit/MaterialInteractions/numrecipes.cc @@ -29,9 +29,8 @@ namespace OrbitUtils{ return sin(x)*exp(-fac1*pow(2*p*sin(x/2), 2))/pow(sin(x/2),4); } - int zbrak(float (*fx)(float, float, float, float), float x1, float x2, - int n, float xb1[], float xb2[], int &nb, float param1, + int n, float *xb1, float *xb2, int &nb, float param1, float param2, float param3) { int nbb, i; @@ -54,7 +53,9 @@ namespace OrbitUtils{ } #undef JMAX +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define JMAX 40 +#endif float rtbis(float (*func)(float, float, float, float), float x1, float x2, float xacc, float param1, float param2, float param3) @@ -134,8 +135,10 @@ namespace OrbitUtils{ #undef EPS #undef JMAX +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define EPS 1.0e-6 #define JMAX 20 +#endif float qsimp(float (*func)(float, float, float), float a, float b, float p, float fac1) @@ -164,7 +167,9 @@ namespace OrbitUtils{ /* note #undef's at end of file */ +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #define FUNC(x, p, fac1) ((*rfunc)(x, p, fac1)) +#endif float trapzd(float (*rfunc)(float, float, float), float a, float b, int n, float p, float fac1) diff --git a/src/orbit/MaterialInteractions/numrecipes.hh b/src/orbit/MaterialInteractions/numrecipes.hh index 25f884e0..8059db80 100644 --- a/src/orbit/MaterialInteractions/numrecipes.hh +++ b/src/orbit/MaterialInteractions/numrecipes.hh @@ -16,7 +16,54 @@ namespace OrbitUtils{ float fstep(float s, float r_o, float pr_o, float theta); float rfunc(float x, float p, float fac1); - int zbrak(float (*fx)(float, float, float, float), float x1, float x2, int n, float xb1[], float xb2[], int &nb, float param1, + + /** + * @brief Bracket subintervals where a function changes sign. + * + * Scans the interval [x1, x2] by dividing it into @p n equal subintervals + * and records subinterval endpoints where the function @p fx changes sign + * (i.e., a root is bracketed). + * + * The function @p fx must have the signature: + * float fx(float x, float p1, float p2, float p3); + * It is evaluated at the grid points x1, x1 + dx, x1 + 2*dx, ..., x2, + * where dx = (x2 - x1) / n. + * + * When an interval [xb1[k], xb2[k]] is found such that fx(xb1[k]) and + * fx(xb2[k]) have opposite signs (fc*fp <= 0), the endpoints are stored + * in the output arrays xb1 and xb2 at the same index k (1-based indexing + * is used internally; the caller should account for this). + * + * @param fx Pointer to the function to examine. Signature: + * float fx(float x, float param1, float param2, float param3). + * @param x1 Left end of the search interval. + * @param x2 Right end of the search interval. + * @param n Number of equal subintervals to split [x1, x2] into. + * @param xb1 Output array to receive left endpoints of bracketing subintervals. + * Must be large enough to hold up to the capacity indicated by the + * integer referenced by @p nb (see @p nb description). + * @param xb2 Output array to receive right endpoints of bracketing subintervals. + * Same required capacity as @p xb1. + * @param nb Reference to an integer indicating the maximum number of bracket + * intervals the caller can accept on input; on return this integer + * is set to the actual number of brackets found (nb <= original nb). + * @param param1 First user parameter passed through to @p fx. + * @param param2 Second user parameter passed through to @p fx. + * @param param3 Third user parameter passed through to @p fx. + * + * @return Returns 0 on completion. If the number of found brackets reaches the + * input capacity (nb), the function returns immediately with xb1/xb2 + * filled up to that capacity and nb set equal to that capacity. + * + * @note + * - The function uses sequential evaluations of @p fx and treats a zero or a + * sign change (fc*fp <= 0.0) as a bracket. Adjacent subintervals that both + * satisfy this condition will each be reported. + * - The implementation uses 1-based indexing internally when filling xb1/xb2. + * The caller should allocate arrays accordingly and interpret the filled + * entries consistent with the calling convention used in the surrounding code. + */ + int zbrak(float (*fx)(float, float, float, float), float x1, float x2, int n, float *xb1, float *xb2, int &nb, float param1, float param2, float param3); float rtbis(float (*func)(float, float, float, float), float x1, float x2, float xacc, float param1, float param2, float param3); float bessj0(float x); diff --git a/src/spacecharge/UniformEllipsoidFieldCalculator.cc b/src/spacecharge/UniformEllipsoidFieldCalculator.cc index 42fc6970..811eb52d 100644 --- a/src/spacecharge/UniformEllipsoidFieldCalculator.cc +++ b/src/spacecharge/UniformEllipsoidFieldCalculator.cc @@ -15,6 +15,7 @@ using namespace OrbitUtils; //macros for max and min +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) #ifndef max #define max( a, b ) ( ((a) > (b)) ? (a) : (b) ) #endif @@ -22,6 +23,7 @@ using namespace OrbitUtils; #ifndef min #define min( a, b ) ( ((a) < (b)) ? (a) : (b) ) #endif +#endif /** Constructor. There is no parameters */ UniformEllipsoidFieldCalculator::UniformEllipsoidFieldCalculator(): CppPyWrapper(NULL) diff --git a/src/utils/Random.cc b/src/utils/Random.cc index c19bafca..4725232a 100644 --- a/src/utils/Random.cc +++ b/src/utils/Random.cc @@ -21,6 +21,7 @@ using namespace OrbitUtils; // By default the random generator is initialized using a random seed (current time) +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) std::mt19937 mt(time(0)); void Random::seed(int seed){ @@ -31,3 +32,4 @@ void Random::seed(int seed){ double Random::ran1(){ return ((double) mt() / (mt.max())); } +#endif From 9aa42951af54da96107ee320a14355a240b7d363 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 12 Jan 2026 14:35:44 -0500 Subject: [PATCH 13/23] Write a new workflow to automatically build and publish docs to GH Pages --- .github/workflows/docs.yml | 30 +++++-- doc/source/_static/.gitkeep | 0 doc/source/_templates/.gitkeep | 0 docs-environment.yml | 149 ++++----------------------------- 4 files changed, 38 insertions(+), 141 deletions(-) create mode 100644 doc/source/_static/.gitkeep create mode 100644 doc/source/_templates/.gitkeep diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ce5f24dc..6f80ac25 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,11 +2,12 @@ name: Deploy Documentation to Pages on: - # Runs on pushes targeting the default branch push: branches: ["main"] - # Allows you to run this workflow manually from the Actions tab + pull_request: + branches: ["main"] + workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages @@ -31,20 +32,37 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - - uses: conda-incubator/setup-miniconda@v2 + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3 with: activate-environment: po3 + channels: conda-forge,defaults + auto-update-conda: true environment-file: docs-environment.yml - - uses: ammaraskar/sphinx-action@master - with: - docs-folder: "doc/" + + - name: Install PyORBIT3 + shell: bash -l {0} + run: | + conda activate po3 + pip install --config-settings=setup-args="-DUSE_MPI='none'" . + + - name: Build Documentation + shell: bash -l {0} + run: | + conda activate po3 + cd doc + make html + # - name: Setup Pages # uses: actions/configure-pages@v5 + - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: # Upload entire repository path: './doc/build/html' + - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 diff --git a/doc/source/_static/.gitkeep b/doc/source/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/doc/source/_templates/.gitkeep b/doc/source/_templates/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs-environment.yml b/docs-environment.yml index 79a24a96..b0584afd 100644 --- a/docs-environment.yml +++ b/docs-environment.yml @@ -2,138 +2,17 @@ name: docs channels: - conda-forge dependencies: - - _openmp_mutex=4.5=7_kmp_llvm - - accessible-pygments=0.0.5=pyhd8ed1ab_1 - - alabaster=0.7.16=pyhd8ed1ab_0 - - babel=2.17.0=pyhd8ed1ab_0 - - backports.zstd=1.2.0=py313hf42fe89_0 - - beautifulsoup4=4.14.3=pyha770c72_0 - - black=25.12.0=pyh866005b_0 - - breathe=4.35.0=pyhd8ed1ab_4 - - brotli=1.2.0=h7d5ae5b_1 - - brotli-bin=1.2.0=hc919400_1 - - brotli-python=1.2.0=py313hde1f3bb_1 - - bzip2=1.0.8=hd037594_8 - - c-ares=1.34.6=hc919400_0 - - ca-certificates=2025.11.12=hbd8a1cb_0 - - certifi=2025.11.12=pyhd8ed1ab_0 - - charset-normalizer=3.4.4=pyhd8ed1ab_0 - - click=8.3.1=pyh8f84b5b_1 - - colorama=0.4.6=pyhd8ed1ab_1 - - contourpy=1.3.3=py313ha61f8ec_3 - - cycler=0.12.1=pyhcf101f3_2 - - docutils=0.17.1=py313h8f79df9_7 - - doxygen=1.13.2=h493aca8_0 - - exhale=0.3.7=pyhd8ed1ab_1 - - fonttools=4.61.1=pyh7db6752_0 - - freetype=2.14.1=hce30654_0 - - h2=4.3.0=pyhcf101f3_0 - - hpack=4.1.0=pyhd8ed1ab_0 - - hyperframe=6.1.0=pyhd8ed1ab_0 - - icu=75.1=hfee45f7_0 - - idna=3.11=pyhd8ed1ab_0 - - imagesize=1.4.1=pyhd8ed1ab_0 - - importlib-metadata=8.7.0=pyhe01879c_1 - - isort=7.0.0=pyhd8ed1ab_0 - - jinja2=3.1.6=pyhcf101f3_1 - - kiwisolver=1.4.9=py313h7add70c_2 - - lcms2=2.17=h7eeda09_0 - - lerc=4.0.0=hd64df32_1 - - libabseil=20250512.1=cxx17_hd41c47c_0 - - libblas=3.11.0=5_h51639a9_openblas - - libbrotlicommon=1.2.0=hc919400_1 - - libbrotlidec=1.2.0=hc919400_1 - - libbrotlienc=1.2.0=hc919400_1 - - libcblas=3.11.0=5_hb0561ab_openblas - - libcxx=21.1.8=hf598326_0 - - libdeflate=1.25=hc11a715_0 - - libev=4.33=h93a5062_2 - - libevent=2.1.12=h2757513_1 - - libexpat=2.7.3=haf25636_0 - - libfabric=2.4.0=hce30654_0 - - libfabric1=2.4.0=hc919400_0 - - libffi=3.5.2=he5f378a_0 - - libfreetype=2.14.1=hce30654_0 - - libfreetype6=2.14.1=h6da58f4_0 - - libgcc=15.2.0=hcbb3090_16 - - libgfortran=15.2.0=h07b0088_16 - - libgfortran5=15.2.0=hdae7583_16 - - libhwloc=2.12.1=default_ha3cc4f2_1003 - - libiconv=1.18=h23cfdf5_2 - - libjpeg-turbo=3.1.2=hc919400_0 - - liblapack=3.11.0=5_hd9741b5_openblas - - liblzma=5.8.1=h39f12f2_2 - - libmpdec=4.0.0=h5505292_0 - - libnghttp2=1.67.0=hc438710_0 - - libopenblas=0.3.30=openmp_ha158390_3 - - libpmix=5.0.8=h3e7ebac_2 - - libpng=1.6.53=hfab5511_0 - - libsqlite=3.51.1=h9a5124b_0 - - libtiff=4.7.1=h4030677_1 - - libuv=1.51.0=h6caf38d_1 - - libwebp-base=1.6.0=h07db88b_0 - - libxcb=1.17.0=hdb1d25a_0 - - libxml2=2.15.1=h9329255_0 - - libxml2-16=2.15.1=h0ff4647_0 - - libxslt=1.1.43=hb2570ba_1 - - libzlib=1.3.1=h8359307_2 - - llvm-openmp=21.1.8=h4a912ad_0 - - lxml=6.0.2=py313he6cafaa_2 - - markupsafe=3.0.3=pyh7db6752_0 - - matplotlib=3.10.8=py313h39782a4_0 - - matplotlib-base=3.10.8=py313h58042b9_0 - - mpi=1.0.1=openmpi - - munkres=1.1.4=pyhd8ed1ab_1 - - mypy_extensions=1.1.0=pyha770c72_0 - - ncurses=6.5=h5e97a16_3 - - nodeenv=1.9.1=pyhd8ed1ab_1 - - nodejs=25.2.1=h5230ea7_1 - - numpy=2.3.5=py313h9771d21_0 - - openjpeg=2.5.4=hbfb3c88_0 - - openmpi=5.0.8=h13a75e3_109 - - openssl=3.6.0=h5503f6c_0 - - packaging=25.0=pyh29332c3_1 - - pathspec=0.12.1=pyhd8ed1ab_1 - - pillow=12.0.0=py313ha86496b_2 - - pip=25.3=pyh145f28c_0 - - platformdirs=4.5.1=pyhcf101f3_0 - - pthread-stubs=0.4=hd74edd7_1002 - - pydata-sphinx-theme=0.13.3=pyhd8ed1ab_0 - - pygments=2.19.2=pyhd8ed1ab_0 - - pyparsing=3.2.5=pyhcf101f3_0 - - pyright=1.1.407=py313h9734d34_0 - - pysocks=1.7.1=pyha55dd90_7 - - python=3.13.11=hfc2f54d_100_cp313 - - python-dateutil=2.9.0.post0=pyhe01879c_2 - - python_abi=3.13=8_cp313 - - pytokens=0.3.0=pyhcf101f3_0 - - pytz=2025.2=pyhd8ed1ab_0 - - qhull=2020.2=h420ef59_5 - - readline=8.3=h46df422_0 - - requests=2.32.5=pyhd8ed1ab_0 - - roman-numerals=4.1.0=pyhd8ed1ab_0 - - scipy=1.16.3=py313h0d10b07_1 - - setuptools=80.9.0=pyhff2d567_0 - - six=1.17.0=pyhe01879c_1 - - snowballstemmer=3.0.1=pyhd8ed1ab_0 - - soupsieve=2.8=pyhd8ed1ab_0 - - sphinx=4.5.0=pyh6c4a22f_0 - - sphinxcontrib-applehelp=1.0.4=pyhd8ed1ab_0 - - sphinxcontrib-devhelp=1.0.2=py_0 - - sphinxcontrib-htmlhelp=2.0.1=pyhd8ed1ab_0 - - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_1 - - sphinxcontrib-qthelp=1.0.3=py_0 - - sphinxcontrib-serializinghtml=1.1.5=pyhd8ed1ab_2 - - standard-imghdr=3.13.0=pyh29332c3_0 - - tk=8.6.13=h892fb3f_3 - - tornado=6.5.4=py313h6535dbc_0 - - typing-extensions=4.15.0=h396c80c_0 - - typing_extensions=4.15.0=pyhcf101f3_0 - - tzdata=2025c=h8577fbf_0 - - unicodedata2=17.0.0=py313h6535dbc_1 - - urllib3=2.6.2=pyhd8ed1ab_0 - - xorg-libxau=1.0.12=hc919400_1 - - xorg-libxdmcp=1.1.5=hc919400_1 - - zipp=3.23.0=pyhcf101f3_1 - - zlib-ng=2.3.2=h248ca61_0 - - zstd=1.5.7=hbf9d68e_6 + - doxygen + - exhale + - pydata-sphinx-theme + - python=3.13 + - sphinx + - breathe + - standard-imghdr + - fftw + - numpy + - scipy + - matplotlib + - meson + - pkg-config + - ninja From cfa00830dc82587350e4140645c52186b57a6188 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Mon, 12 Jan 2026 16:35:52 -0500 Subject: [PATCH 14/23] Don't build docs on PR Building and re-deploying on each PR may be problematic as the github-pages environment is protected. --- .github/workflows/docs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6f80ac25..1d89d168 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,9 +5,6 @@ on: push: branches: ["main"] - pull_request: - branches: ["main"] - workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages From c66b2905a578183d8c217e5400a5b5e0f57d719a Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 10:51:08 -0500 Subject: [PATCH 15/23] Add markdown support and 'copy' button on codeblocks --- README.md | 23 ++--- doc/source/conf.py | 3 + doc/source/index.rst | 2 +- doc/source/install.md | 1 + doc/source/install.rst | 193 ----------------------------------------- docs-environment.yml | 2 + 6 files changed, 20 insertions(+), 204 deletions(-) create mode 120000 doc/source/install.md delete mode 100644 doc/source/install.rst diff --git a/README.md b/README.md index 8e5b4277..b896f29f 100644 --- a/README.md +++ b/README.md @@ -29,16 +29,16 @@ The following commands may require root access.
Click for Ubuntu-based distributions - + ```bash apt-get update apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git - ``` + ```
Click for Redhat-based distributions - + ```bash dnf group install -y "Development Tools" dnf install -y python3-devel fftw3-devel @@ -47,16 +47,18 @@ The following commands may require root access.
Click for Mac - + Install Homebrew, make sure that homebrew programs are in the **$PATH** (optional step in Homebrew installation) + ```bash brew install pkg-config fftw ```
- + #### Create Python virtual environment Make sure that you have the correct python version installed. We require python>3.9.
Create virtual environment. + ``` python3 -m venv .po3 . .po3/bin/activate @@ -70,6 +72,7 @@ The following commands may require root access. First of all make sure you have conda installed and development packages.
Development packages for Ubuntu: + ``` apt update -y apt install -y curl gpg git build-essential @@ -87,18 +90,18 @@ pip install -U meson-python setuptools setuptools-scm ## 3. Build -If you plan to modify PyORBIT's code, install it in editable mode. +If you plan to modify PyORBIT's code, install it in editable mode. You will NOT need to rebuild after modifications to the code. [Meson](MesonBuild.md) will rebuild as necessary on import. ``` pip install --no-build-isolation --editable . ``` Alternatively if you don't plan to modify PyORBIT's code + ``` pip install . ``` - ## 4. Run full SNS linac example Navigate to your **examples** directory and launch tracking of SNS linac. @@ -116,9 +119,9 @@ pip install --config-settings=setup-args="-DUSE_MPI=none" . Above will build PyORBIT without MPI even if MPI is present. You can change that option to `mpich`, `ompi`, `none` or `auto` (default).
| MPI flavor | Installation command | |---------------|--------------| -| No MPI | `pip install --config-settings=setup-args="-DUSE_MPI=none" .` | -| The first found MPI installation if any | `pip install --config-settings=setup-args="-DUSE_MPI=auto" .` | -| OpenMPI | `pip install --config-settings=setup-args="-DUSE_MPI=ompi" .` | +| No MPI | `pip install --config-settings=setup-args="-DUSE_MPI=none" .` | +| The first found MPI installation if any | `pip install --config-settings=setup-args="-DUSE_MPI=auto" .` | +| OpenMPI | `pip install --config-settings=setup-args="-DUSE_MPI=ompi" .` | | MPICH | `pip install --config-settings=setup-args="-DUSE_MPI=mpich" .` | Meson uses PKG_CONFIG to discover packages. It could be useful to help it to find your MPI installation: diff --git a/doc/source/conf.py b/doc/source/conf.py index 1a9dc3d4..1a1dec2c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -27,8 +27,11 @@ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', + 'sphinx_copybutton', + 'myst_parser', 'breathe', 'exhale'] + napoleon_numpy_docstring = True autosummary_imported_members = True diff --git a/doc/source/index.rst b/doc/source/index.rst index 7d38cecb..0afbf680 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,7 +10,7 @@ PyORBIT3 :maxdepth: 2 :caption: Getting Started - install + install.md .. toctree:: :maxdepth: 2 diff --git a/doc/source/install.md b/doc/source/install.md new file mode 120000 index 00000000..fe840054 --- /dev/null +++ b/doc/source/install.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/doc/source/install.rst b/doc/source/install.rst deleted file mode 100644 index a8978c20..00000000 --- a/doc/source/install.rst +++ /dev/null @@ -1,193 +0,0 @@ -Installation -============================= - -1. Introduction ---------------- - -This guide provides instructions how to install PyORBIT code. This guide -doesn’t cover MPI enabled installation. The following configurations are -included in CI testing, versions will change as the runner images -progress. - -+------------+-----------+------------+-------+-----------+-----------+ -| HW | Arc | OS | P | Compiler | Package | -| | hitecture | | ython | | | -+============+===========+============+=======+===========+===========+ -| PC | x86_64 | CentOS | 3 | g | pip-24.0 | -| | | latest | .9.18 | cc-11.4.1 | | -+------------+-----------+------------+-------+-----------+-----------+ -| PC | x86_64 | Ubuntu | 3 | g | pip-24.0 | -| | | latest | .12.3 | cc-13.2.0 | | -+------------+-----------+------------+-------+-----------+-----------+ -| Apple | arm64 | macOS 14 | 3 | cla | pip-24.0 | -| Silicon | | | .12.3 | ng-15.0.0 | | -+------------+-----------+------------+-------+-----------+-----------+ -| PC | x86_64 | Ubuntu | 3. | g | con | -| | | latest | 10.14 | cc-13.2.0 | da-24.5.0 | -+------------+-----------+------------+-------+-----------+-----------+ - -2. Installation from source ---------------------------- - -First step is to clone the source code: - -.. code:: bash - - git clone https://github.com/PyORBIT-Collaboration/PyORBIT3.git - -Pip Setup -~~~~~~~~~ - -**PIP** based setup is more involved, we recommend using **conda** if -unsure. #### Prepare OS The following commands may require root access. - -.. raw:: html - -
- -.. raw:: html - - - -Click for Ubuntu-based distributions - -.. raw:: html - - - -.. code:: bash - - apt-get update - apt-get install -y build-essential python3 libfftw3-dev python3-venv libpython3-dev pkg-config git - -.. raw:: html - -
- -.. raw:: html - -
- -.. raw:: html - - - -Click for Redhat-based distributions - -.. raw:: html - - - -.. code:: bash - - dnf group install -y "Development Tools" - dnf install -y python3-devel fftw3-devel - -.. raw:: html - -
- -.. raw:: html - -
- -.. raw:: html - - - -Click for Mac - -.. raw:: html - - - -Install Homebrew, make sure that homebrew programs are in the **$PATH** -(optional step in Homebrew installation) -``bash brew install pkg-config fftw`` - -.. raw:: html - -
- -#### Create Python virtual environment Make sure that you have the -correct python version installed. We require python>3.9. Create virtual -environment. -``python3 -m venv .po3 . .po3/bin/activate pip install -U pip pip install -r requirements.txt pip install -U setuptools`` - -Conda Setup -~~~~~~~~~~~ - -First of all make sure you have conda installed and development -packages. Development packages for Ubuntu: - -:: - - apt update -y - apt install -y curl gpg git build-essential - -Then run the following: - -.. code:: bash - - cd pyorbit3 - conda env create -n po3 --file environment.yml - conda activate po3 - pip install -U meson-python setuptools setuptools-scm - -3. Build --------- - -If you plan to modify PyORBIT’s code, install it in editable mode. You -will NOT need to rebuild after modifications to the code. -`Meson `__ will rebuild as necessary on import. - -:: - - pip install --no-build-isolation --editable . - -Alternatively if you don’t plan to modify PyORBIT’s code - -:: - - pip install . - -4. Run full SNS linac example ------------------------------ - -Navigate to your **examples** directory and launch tracking of SNS -linac. - -.. code:: bash - - cd examples/SNS_Linac/pyorbit3_linac_model/ - python pyorbit3_sns_linac_mebt_hebt2.py - -5. MPI consideration --------------------- - -By default, the build system will try to find MPI and compile against -it. You can control which MPI to use with command line option when -building. - -.. code:: bash - - pip install --config-settings=setup-args="-DUSE_MPI=none" . - -Above will build PyORBIT without MPI even if MPI is present. You can -change that option to ``mpich``, ``ompi``, ``none`` or ``auto`` -(default). \| MPI flavor \| Installation command \| \|—————\|————–\| \| -No MPI \| -``pip install --config-settings=setup-args="-DUSE_MPI=none" .`` \| \| -The first found MPI installation if any \| -``pip install --config-settings=setup-args="-DUSE_MPI=auto" .`` \| \| -OpenMPI \| -``pip install --config-settings=setup-args="-DUSE_MPI=ompi" .`` \| \| -MPICH \| -``pip install --config-settings=setup-args="-DUSE_MPI=mpich" .`` \| - -Meson uses PKG_CONFIG to discover packages. It could be useful to help -it to find your MPI installation: - -.. code:: bash - - PKG_CONFIG_PATH=/opt/lib/pkgconfig pip install --verbose . diff --git a/docs-environment.yml b/docs-environment.yml index b0584afd..f27037c3 100644 --- a/docs-environment.yml +++ b/docs-environment.yml @@ -7,6 +7,8 @@ dependencies: - pydata-sphinx-theme - python=3.13 - sphinx + - sphinx-copybutton + - myst-parser - breathe - standard-imghdr - fftw From 59ce106b07ce4132810ff26d2f2e041ba475f80f Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 10:53:35 -0500 Subject: [PATCH 16/23] formatting --- doc/source/conf.py | 79 ++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 1a1dec2c..8f0fd2f5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -5,7 +5,6 @@ # -- Path setup -------------------------------------------------------------- import sys -import pathlib from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent / "py/")) @@ -13,63 +12,67 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'PyORBIT3' -copyright = '2025, PyORBIT Collaboration' -author = 'PyORBIT Collaboration' -release = 'v3.0.1' +project = "PyORBIT3" +copyright = "2025, PyORBIT Collaboration" +author = "PyORBIT Collaboration" +release = "v3.0.1" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.coverage', - 'sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.napoleon', - 'sphinx_copybutton', - 'myst_parser', - 'breathe', - 'exhale'] +extensions = [ + "sphinx.ext.coverage", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx_copybutton", + "myst_parser", + "breathe", + "exhale", +] napoleon_numpy_docstring = True autosummary_imported_members = True -templates_path = ['_templates'] +templates_path = ["_templates"] exclude_patterns = [] # -- Breathe and Exhale Options --------------------------------------------------------- breathe_projects = { - "PyORBIT3": "./_doxygen/xml", - } + "PyORBIT3": "./_doxygen/xml", +} breathe_default_project = "PyORBIT3" -doxyfile = '\n'.join([ - "INPUT = ../../src", - "EXCLUDE_PATTERNS = *wrap* *_init.cc", - "PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS", - "PREDEFINED += PyObject_HEAD=\"PyObject ob_base;\"" - ]) +doxyfile = "\n".join( + [ + "INPUT = ../../src", + "EXCLUDE_PATTERNS = *wrap* *_init.cc", + "PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS", + 'PREDEFINED += PyObject_HEAD="PyObject ob_base;"', + ] +) exhale_args = { - "containmentFolder": "./api", - "rootFileName": "pyorbit_root.rst", - "doxygenStripFromPath": "..", - "rootFileTitle": "PyORBIT3 C++ API", - "createTreeView": True, - "exhaleExecutesDoxygen": True, - "exhaleDoxygenStdin": doxyfile, - } + "containmentFolder": "./api", + "rootFileName": "pyorbit_root.rst", + "doxygenStripFromPath": "..", + "rootFileTitle": "PyORBIT3 C++ API", + "createTreeView": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": doxyfile, +} # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'pydata_sphinx_theme' -html_static_path = ['_static'] +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] html_show_source_link = True html_theme_options = { - 'github_url': 'https://github.com/PyORBIT-Collaboration/PyORBIT3', - 'logo': { - 'text': "PyORBIT3", - } + "github_url": "https://github.com/PyORBIT-Collaboration/PyORBIT3", + "logo": { + "text": "PyORBIT3", + }, } From 40c83cc8f382c0b8d8c4662e5cc2f7425181ed23 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 10:59:57 -0500 Subject: [PATCH 17/23] remove comments --- .github/workflows/docs.yml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1d89d168..bc538460 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,3 @@ -# Simple workflow for deploying static content to GitHub Pages name: Deploy Documentation to Pages on: @@ -20,7 +19,6 @@ concurrency: cancel-in-progress: false jobs: - # Single deploy job since we're just deploying deploy: environment: name: github-pages @@ -41,6 +39,7 @@ jobs: - name: Install PyORBIT3 shell: bash -l {0} run: | + # @woodtp -- MPI isn't required to build docs and enabling it causes Sphinx to segfault. conda activate po3 pip install --config-settings=setup-args="-DUSE_MPI='none'" . @@ -51,13 +50,9 @@ jobs: cd doc make html - # - name: Setup Pages - # uses: actions/configure-pages@v5 - - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - # Upload entire repository path: './doc/build/html' - name: Deploy to GitHub Pages From bce103fbf1395b790a2c65ec6001d356b9e390a0 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 11:36:19 -0500 Subject: [PATCH 18/23] split into two jobs so that build and deploy can be re-run independently if necessary --- .github/workflows/docs.yml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bc538460..9ca1aca7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,10 +19,7 @@ concurrency: cancel-in-progress: false jobs: - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} + build: runs-on: ubuntu-latest steps: - name: Checkout @@ -55,6 +52,13 @@ jobs: with: path: './doc/build/html' + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 From 5f422a45c43d8f7dec34fb81d8ceb82be2ce46d3 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 12:12:56 -0500 Subject: [PATCH 19/23] Extend deploy job timeout to 1 hour If things are really busy, the default 10 minutes is an insufficient amount of time to wait in the queue. --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9ca1aca7..d8d65c8d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -62,3 +62,5 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 + with: + timeout: 3600000 From 0d6552e8b80c126dec46343d1917b3fdde19e7b9 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 14:18:03 -0500 Subject: [PATCH 20/23] Move doc building to a resuable workflow Now docs can be built on pull request without attempting to publish to Pages. --- .github/workflows/compilation.yml | 17 +++++++------ .github/workflows/docs-build.yml | 42 +++++++++++++++++++++++++++++++ .github/workflows/docs.yml | 34 +++---------------------- 3 files changed, 55 insertions(+), 38 deletions(-) create mode 100644 .github/workflows/docs-build.yml diff --git a/.github/workflows/compilation.yml b/.github/workflows/compilation.yml index c06d3621..c40130af 100644 --- a/.github/workflows/compilation.yml +++ b/.github/workflows/compilation.yml @@ -34,8 +34,8 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh - + .github/workflows/pip-versions.sh + centos-stream: runs-on: ubuntu-latest @@ -60,8 +60,8 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh - + .github/workflows/pip-versions.sh + ubuntu: @@ -88,7 +88,7 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh + .github/workflows/pip-versions.sh conda: @@ -120,7 +120,7 @@ jobs: - name: Print Versions run: | - .github/workflows/conda-versions.sh + .github/workflows/conda-versions.sh mpich: runs-on: ubuntu-latest @@ -145,4 +145,7 @@ jobs: - name: Print Versions run: | - .github/workflows/pip-versions.sh \ No newline at end of file + .github/workflows/pip-versions.sh + + build-docs: + uses: ./.github/workflows/docs-build.yml diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml new file mode 100644 index 00000000..7d49d10e --- /dev/null +++ b/.github/workflows/docs-build.yml @@ -0,0 +1,42 @@ +on: + workflow_call: + inputs: + upload-artifact: + required: false + type: boolean + default: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3 + with: + activate-environment: po3 + channels: conda-forge,defaults + auto-update-conda: true + environment-file: docs-environment.yml + + - name: Install PyORBIT3 + shell: bash -l {0} + run: | + # @woodtp -- MPI isn't required to build docs and enabling it causes Sphinx to segfault. + conda activate po3 + pip install --config-settings=setup-args="-DUSE_MPI='none'" . + + - name: Build Documentation + shell: bash -l {0} + run: | + conda activate po3 + cd doc + make html + + - name: Upload artifact + if: ${{ inputs.upload-artifact }} + uses: actions/upload-pages-artifact@v3 + with: + path: './doc/build/html' diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d8d65c8d..679aee4e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,37 +20,9 @@ concurrency: jobs: build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Miniconda - uses: conda-incubator/setup-miniconda@v3 - with: - activate-environment: po3 - channels: conda-forge,defaults - auto-update-conda: true - environment-file: docs-environment.yml - - - name: Install PyORBIT3 - shell: bash -l {0} - run: | - # @woodtp -- MPI isn't required to build docs and enabling it causes Sphinx to segfault. - conda activate po3 - pip install --config-settings=setup-args="-DUSE_MPI='none'" . - - - name: Build Documentation - shell: bash -l {0} - run: | - conda activate po3 - cd doc - make html - - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: './doc/build/html' + uses: ./.github/workflows/docs-build.yml + with: + upload-artifact: true deploy: needs: build From cdc67ff4bd612ea62d3b7396b7ee867ad94a9834 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 14:51:18 -0500 Subject: [PATCH 21/23] this needs quotes ..? --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 679aee4e..67ae0d30 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,4 +35,4 @@ jobs: id: deployment uses: actions/deploy-pages@v4 with: - timeout: 3600000 + timeout: '3600000' From 433c3ff536931a9efbd1769dc7756a7efc0add02 Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 15:13:10 -0500 Subject: [PATCH 22/23] Revert "this needs quotes ..?" This reverts commit cdc67ff4bd612ea62d3b7396b7ee867ad94a9834. --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 67ae0d30..679aee4e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,4 +35,4 @@ jobs: id: deployment uses: actions/deploy-pages@v4 with: - timeout: '3600000' + timeout: 3600000 From a597e3a1d017ee71248e2e9de8c637ebd7b3070b Mon Sep 17 00:00:00 2001 From: "Wood, Tony" Date: Tue, 13 Jan 2026 15:13:18 -0500 Subject: [PATCH 23/23] Revert "Extend deploy job timeout to 1 hour" This reverts commit 5f422a45c43d8f7dec34fb81d8ceb82be2ce46d3. --- .github/workflows/docs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 679aee4e..4bfcdd70 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -34,5 +34,3 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 - with: - timeout: 3600000