From 30278d0cfe83e076f6e8eda44a89e2ff9bd77b7c Mon Sep 17 00:00:00 2001 From: liuzzo Date: Fri, 31 Oct 2025 14:50:15 +0100 Subject: [PATCH 1/9] better doc --- docs/conf.py | 5 ++++- docs/index.rst | 31 +++++++++++++++++++++---------- docs/modules/core_functions.rst | 8 -------- docs/modules/tuning_tools.rst | 10 +++++----- pyaml/pyaml.py | 21 +++++++++++++++++++-- tests/config/EBSTune.yaml | 6 ------ 6 files changed, 49 insertions(+), 32 deletions(-) delete mode 100644 docs/modules/core_functions.rst diff --git a/docs/conf.py b/docs/conf.py index 9dcc6466..63b18d82 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,6 +53,7 @@ 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', 'sphinx.ext.autosectionlabel', + 'sphinx.ext.autosummary', ] autosectionlabel_prefix_document = True autosectionlabel_maxdepth = 2 @@ -92,7 +93,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -120,6 +121,8 @@ 'display_version': True, 'logo_only': True, 'navigation_depth': 2, + "rightsidebar": "false", + "relbarbgcolor": "black" } diff --git a/docs/index.rst b/docs/index.rst index 742c7411..1a604601 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,11 @@ pyAML documentation -=================== +====================================== + +.. contents:: Table of Contents + :depth: 3 Introduction ------------- +------------------------ python Accelerator Middle Layer (pyAML) is a joint technology platform to develop common tools for control, tuning and development of storage rings, beam transport lines and linear accelerators. @@ -17,7 +20,7 @@ With pyAML, it WILL be possible to (the software is at conceptualization stage): - many more features Installation ------------- +------------------------ pip support will be provided later. for the time being: @@ -25,17 +28,17 @@ git clone https://github.com/python-accelerator-middle-layer/pyaml.git Collaboration community ------------- +------------------------ Discussion -~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ `Mattermost `_ (please log in using Helmoltz ID, you will be prompt to access with your own lab/university credentials) Shared documents -~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ to access the shared documents please ask S.Liuzzo for access rigths. @@ -45,12 +48,12 @@ https://www.overleaf.com/read/hnrqzhfpbvpp#ef8935 to be added to editors list please write to S.Liuzzo Mailing list: -~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ to be added to the pyAML mailing list please write to S.Liuzzo -Package Reference -================= +Documentation +---------------------- .. toctree:: :caption: Modules @@ -60,8 +63,16 @@ Package Reference modules/* +List of all modules +---------------- + +.. toctree:: + + api + + Indices and tables -================== +==================================== * :ref:`genindex` * :ref:`modindex` diff --git a/docs/modules/core_functions.rst b/docs/modules/core_functions.rst deleted file mode 100644 index f40da13e..00000000 --- a/docs/modules/core_functions.rst +++ /dev/null @@ -1,8 +0,0 @@ -Core functions -************************** - -.. automodule:: pyAML.pyaml - :members: - -.. automodule:: pyAML.device - :members: diff --git a/docs/modules/tuning_tools.rst b/docs/modules/tuning_tools.rst index c831b829..858702b7 100644 --- a/docs/modules/tuning_tools.rst +++ b/docs/modules/tuning_tools.rst @@ -1,11 +1,11 @@ -Tuning Tools -************************** +Tuning tools +*************** -.. automodule:: tuning_tools.LOCO.loco +.. automodule:: pyaml.tuning_tools.LOCO.loco :members: -.. automodule:: tuning_tools.SOFB.sofb +.. automodule:: pyaml.tuning_tools.SOFB.sofb :members: -.. automodule:: tuning_tools.TUNE.tune +.. automodule:: pyaml.tuning_tools.TUNE.tune :members: diff --git a/pyaml/pyaml.py b/pyaml/pyaml.py index 7480a704..59e4daa5 100644 --- a/pyaml/pyaml.py +++ b/pyaml/pyaml.py @@ -22,7 +22,17 @@ class ConfigModel(BaseModel): """Instrument name""" class PyAML(object): - """PyAML top level class""" + """ + PyAML top level class + + Allows to + read and set magents and RF + read diagnostics + run tuning tools + For any control system + In a simulator or in the real machine + + """ def __init__(self, cfg: ConfigModel): self._cfg = cfg @@ -36,7 +46,14 @@ def get(self,name:str) -> Instrument: return self.INSTRUMENTS[name] def pyaml(filename:str) -> PyAML: - """Load an accelerator middle layer""" + r""" + Load an accelerator middle layer + + Parameters: + filename: configuration file. + Returns: + accelerator middle layer object. + """ logger.log(logging.INFO, f"Loading PyAML from file '{filename}'") # Asume that all files are referenced from folder where main AML file is stored diff --git a/tests/config/EBSTune.yaml b/tests/config/EBSTune.yaml index dac1fc72..e54adae4 100644 --- a/tests/config/EBSTune.yaml +++ b/tests/config/EBSTune.yaml @@ -7,16 +7,10 @@ instruments: - type: pyaml.lattice.simulator lattice: sr/lattices/ebs.mat name: design - controls: - - type: tango.pyaml.controlsystem - tango_host: ebs-simu-3:10000 - name: live data_folder: /data/store arrays: - type: pyaml.arrays.magnet name: QForTune - aggregator: - type: tango.pyaml.multi_attribute elements: - QD2E-C04 - QD2A-C05 From 6bcb54723fdda2a5e97ec0e8fded1f558ab2a766 Mon Sep 17 00:00:00 2001 From: liuzzo Date: Fri, 31 Oct 2025 14:51:30 +0100 Subject: [PATCH 2/9] doc files --- docs/api.rst | 8 ++++++++ docs/modules/arrays.rst | 11 +++++++++++ docs/modules/bpm.rst | 14 ++++++++++++++ docs/modules/configuration.rst | 29 +++++++++++++++++++++++++++++ docs/modules/control.rst | 23 +++++++++++++++++++++++ docs/modules/lattice.rst | 25 +++++++++++++++++++++++++ docs/modules/magnet.rst | 5 +++++ docs/modules/pyaml.rst | 24 ++++++++++++++++++++++++ docs/modules/rf.rst | 9 +++++++++ 9 files changed, 148 insertions(+) create mode 100644 docs/api.rst create mode 100644 docs/modules/arrays.rst create mode 100644 docs/modules/bpm.rst create mode 100644 docs/modules/configuration.rst create mode 100644 docs/modules/control.rst create mode 100644 docs/modules/lattice.rst create mode 100644 docs/modules/magnet.rst create mode 100644 docs/modules/pyaml.rst create mode 100644 docs/modules/rf.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..b68bd568 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,8 @@ +API +=== + +.. autosummary:: + :toctree: generated + :recursive: + + pyaml \ No newline at end of file diff --git a/docs/modules/arrays.rst b/docs/modules/arrays.rst new file mode 100644 index 00000000..bccaed2c --- /dev/null +++ b/docs/modules/arrays.rst @@ -0,0 +1,11 @@ +ARRAYS +******** + +.. automodule:: pyaml.arrays.array + :members: + +.. automodule:: pyaml.arrays.magnet + :members: + +.. automodule:: pyaml.arrays.magnet_array + :members: diff --git a/docs/modules/bpm.rst b/docs/modules/bpm.rst new file mode 100644 index 00000000..f5ff7867 --- /dev/null +++ b/docs/modules/bpm.rst @@ -0,0 +1,14 @@ +BPMS +***************** + +.. automodule:: pyaml.bpm.bpm + :members: + +.. automodule:: pyaml.bpm.bpm_model + :members: + +.. automodule:: pyaml.bpm.bpm_tilt_offset_model + :members: + +.. automodule:: pyaml.bpm.bpm_simple_model + :members: \ No newline at end of file diff --git a/docs/modules/configuration.rst b/docs/modules/configuration.rst new file mode 100644 index 00000000..dc44a648 --- /dev/null +++ b/docs/modules/configuration.rst @@ -0,0 +1,29 @@ +Configuration +***************** + +.. automodule:: pyaml.configuration.fileloader + :members: + +.. automodule:: pyaml.configuration.factory + :members: + +.. automodule:: pyaml.configuration.matrix + :members: + +.. automodule:: pyaml.configuration.curve + :members: + +.. automodule:: pyaml.configuration.csvcurve + :members: + +.. automodule:: pyaml.configuration.matrix + :members: + +.. automodule:: pyaml.configuration.csvmatrix + :members: + +.. automodule:: pyaml.configuration.models + :members: + +.. automodule:: pyaml.configuration.config_exception + :members: diff --git a/docs/modules/control.rst b/docs/modules/control.rst new file mode 100644 index 00000000..62cf3dbb --- /dev/null +++ b/docs/modules/control.rst @@ -0,0 +1,23 @@ +Control +********* + +.. automodule:: pyaml.control.controlsystem + :members: + +.. automodule:: pyaml.control.device + :members: + +.. automodule:: pyaml.control.abstract_impl + :members: + +.. automodule:: pyaml.control.abstract + :members: + +.. automodule:: pyaml.control.deviceaccess + :members: + +.. automodule:: pyaml.control.deviceaccesslist + :members: + +.. automodule:: pyaml.control.readback_value + :members: diff --git a/docs/modules/lattice.rst b/docs/modules/lattice.rst new file mode 100644 index 00000000..781c017e --- /dev/null +++ b/docs/modules/lattice.rst @@ -0,0 +1,25 @@ +lattice +************ + +.. automodule:: pyaml.lattice.abstract_impl + :members: + +.. automodule:: pyaml.lattice.attribute_linker + :members: + +.. automodule:: pyaml.lattice.element_holder + :members: + +.. automodule:: pyaml.lattice.element + :members: + +.. automodule:: pyaml.lattice.lattice_element_linker + :members: + +.. automodule:: pyaml.lattice.polynom_info + :members: + +.. automodule:: pyaml.lattice.simulator + :members: + + diff --git a/docs/modules/magnet.rst b/docs/modules/magnet.rst new file mode 100644 index 00000000..93f59016 --- /dev/null +++ b/docs/modules/magnet.rst @@ -0,0 +1,5 @@ +magnets +********* + +.. automodule:: pyaml.magnet + :members: diff --git a/docs/modules/pyaml.rst b/docs/modules/pyaml.rst new file mode 100644 index 00000000..fd258108 --- /dev/null +++ b/docs/modules/pyaml.rst @@ -0,0 +1,24 @@ +pyaml +************************** + +.. automodule:: pyaml.pyaml + :members: + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +.. automodule:: pyaml.instrument + :members: + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +.. automodule:: pyaml.exception + :members: + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + diff --git a/docs/modules/rf.rst b/docs/modules/rf.rst new file mode 100644 index 00000000..2d5a3b62 --- /dev/null +++ b/docs/modules/rf.rst @@ -0,0 +1,9 @@ +RF +**** + +.. automodule:: pyaml.rf.rf_plant + :members: + +.. automodule:: pyaml.rf.rf_transmitter + :members: + From 47365eac007a7a28507cb787ff07764769c842aa Mon Sep 17 00:00:00 2001 From: liuzzo Date: Fri, 31 Oct 2025 16:05:16 +0100 Subject: [PATCH 3/9] restore main files not related to doc --- pyaml/pyaml.py | 21 ++------------------- tests/config/EBSTune.yaml | 6 ++++++ 2 files changed, 8 insertions(+), 19 deletions(-) diff --git a/pyaml/pyaml.py b/pyaml/pyaml.py index 59e4daa5..7480a704 100644 --- a/pyaml/pyaml.py +++ b/pyaml/pyaml.py @@ -22,17 +22,7 @@ class ConfigModel(BaseModel): """Instrument name""" class PyAML(object): - """ - PyAML top level class - - Allows to - read and set magents and RF - read diagnostics - run tuning tools - For any control system - In a simulator or in the real machine - - """ + """PyAML top level class""" def __init__(self, cfg: ConfigModel): self._cfg = cfg @@ -46,14 +36,7 @@ def get(self,name:str) -> Instrument: return self.INSTRUMENTS[name] def pyaml(filename:str) -> PyAML: - r""" - Load an accelerator middle layer - - Parameters: - filename: configuration file. - Returns: - accelerator middle layer object. - """ + """Load an accelerator middle layer""" logger.log(logging.INFO, f"Loading PyAML from file '{filename}'") # Asume that all files are referenced from folder where main AML file is stored diff --git a/tests/config/EBSTune.yaml b/tests/config/EBSTune.yaml index e54adae4..dac1fc72 100644 --- a/tests/config/EBSTune.yaml +++ b/tests/config/EBSTune.yaml @@ -7,10 +7,16 @@ instruments: - type: pyaml.lattice.simulator lattice: sr/lattices/ebs.mat name: design + controls: + - type: tango.pyaml.controlsystem + tango_host: ebs-simu-3:10000 + name: live data_folder: /data/store arrays: - type: pyaml.arrays.magnet name: QForTune + aggregator: + type: tango.pyaml.multi_attribute elements: - QD2E-C04 - QD2A-C05 From b4428a3ce8cc1ab4a0f071fa04c8ccfae6602bb4 Mon Sep 17 00:00:00 2001 From: liuzzo Date: Fri, 31 Oct 2025 16:08:55 +0100 Subject: [PATCH 4/9] removed api list of modules, giving recursion error and not usefull --- docs/index.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 1a604601..696a42fc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,12 +63,11 @@ Documentation modules/* -List of all modules ----------------- +.. List of all modules +.. ---------------- -.. toctree:: - - api +.. .. toctree:: +.. api Indices and tables From 3834c6e4c772087be38bac47b6afba9a427cd25c Mon Sep 17 00:00:00 2001 From: liuzzo Date: Fri, 31 Oct 2025 16:15:49 +0100 Subject: [PATCH 5/9] removed api --- docs/index.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 696a42fc..ef8b087e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,13 +63,6 @@ Documentation modules/* -.. List of all modules -.. ---------------- - -.. .. toctree:: -.. api - - Indices and tables ==================================== From 06acb93cc207b5e52636afe93e26adbc9647b35d Mon Sep 17 00:00:00 2001 From: liuzzo Date: Fri, 31 Oct 2025 16:21:54 +0100 Subject: [PATCH 6/9] removed mathjax extension --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 63b18d82..e2a0a714 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,7 +48,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.mathjax', + # 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', From 8accddd5adef380cd91ac11d47a9d6f692553b45 Mon Sep 17 00:00:00 2001 From: liuzzo Date: Tue, 4 Nov 2025 13:15:36 +0100 Subject: [PATCH 7/9] sphinx version increased in requirements --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 94c3dcfa..1f414a18 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ -sphinx==8.1.3 +sphinx==8.2.3 sphinx-book-theme==1.1.3 sphinx-copybutton==0.5.2 sphinx-design==0.6.1 From 5c9e4fe6f61f67945519731e876f0d4d17ab54f1 Mon Sep 17 00:00:00 2001 From: liuzzo Date: Tue, 4 Nov 2025 13:16:08 +0100 Subject: [PATCH 8/9] increased python version for doc building --- .github/workflows/documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 0cfe5026..d77783d6 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -19,7 +19,7 @@ jobs: strategy: matrix: # only lowest supported Python on latest ubuntu os: [ubuntu-latest] - python-version: [3.9] + python-version: [3.14] permissions: issues: write From 4f3643d2b3bfc6de96b621aa3c89b2a9dab9d813 Mon Sep 17 00:00:00 2001 From: liuzzo Date: Tue, 4 Nov 2025 13:16:56 +0100 Subject: [PATCH 9/9] comment --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index e2a0a714..167114d9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# pyAML documentation build configuration file, originally created for pySC: https://github.com/lmalina/pySC/blob/master/doc/conf.py +# pyAML documentation build configuration file, # # This file is execfile()d with the current directory set to its # containing dir.