Doc: changed theme (AT theme) and added draft how-to's from notebooks

.github/workflows/documentation.yml

@@ -47,6 +47,9 @@ jobs:
       - name: Install package
         run: python -m pip install '.[docs]'
 
+      - name: Install dependencies
+        run: pip install -r ./docs/requirements.txt
+
       - name: Build documentation
         run: python -m sphinx -b html docs ./docs/_build -d ./docs/_build
 

README.md

@@ -16,3 +16,15 @@ Disclaimer: the pyAML software is still under development.
    ```
 4. If you want to try the examples using the TANGO bindings you also need [tango-pyaml](https://github.com/python-accelerator-middle-layer/tango-pyaml).
    Clone that repository and install the package inside the same virtual environment as the `pyaml` package.
+   tango-pyaml will automatically install pyaml, so step 3 can be skipped.
+5. For tests, you may want to install dummy-cs/tango available in
+   tests/dummy-cs/tango
+
+#### Documentation
+
+The documentation is hosted on Read the Docs: [pyaml](https://pyaml.readthedocs.io/en/latest/?badge=latest).
+
+#### Examples
+
+Examples are available in the `examples` folder of the repository.
+Additionally, in the documentation there are example Jupyter notebooks available.

docs/conf.py

@@ -48,12 +48,13 @@
               'sphinx.ext.doctest',
               'sphinx.ext.todo',
               'sphinx.ext.coverage',
-              # 'sphinx.ext.mathjax',
+              'sphinx.ext.mathjax',
               'sphinx.ext.viewcode',
               'sphinx.ext.githubpages',
               'sphinx.ext.napoleon',
               'sphinx.ext.autosectionlabel',
               'sphinx.ext.autosummary',
+              'myst_nb'
               ]
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
@@ -111,7 +112,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'classic'
+
+# html_theme = 'classic'
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -120,8 +123,8 @@
     'collapse_navigation': False,
     'display_version': True,
     'logo_only': True,
-    'navigation_depth': 2,
-    "rightsidebar": "false",
+    'navigation_depth': 6,
+    "rightsidebar": True,
     "relbarbgcolor": "black"
 }
 
@@ -131,6 +134,14 @@
 # It is placed at the top of the sidebar;
 # its width should therefore not exceed 200 pixels.
 html_logo = '_static/img/logo.png'
+html_copy_source = False
+html_theme_options = {
+    "github_url": "https://github.com/atcollab/at",
+    "logo": {
+      "image_light": '_static/img/logo.png',
+      "image_dark": '_static/img/dark.png',
+   }
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -169,9 +180,12 @@
     '**': [
         'relations.html',  # needs 'show_related': True theme option to display
         'searchbox.html',
-    ]
+    ],
+    "index": [],
+    "common/about": [],
 }
 
+
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
@@ -231,4 +245,17 @@
 # at building time. Here used to have PyQT mocked.
 autodoc_mock_imports = ['PyQt5', 'PyQt5.QtGui', 'PyQt5.QtCore', 'PyQt5.QtWidgets',
                         "matplotlib.backends.backend_qt5agg",
-                        ]
+                        ]
+
+# -- Options for the myst markdown parser ------------------------------------
+
+myst_enable_extensions = [
+    "attrs_inline",
+    "colon_fence",
+    "dollarmath",
+    "replacements",
+    "deflist",
+]
+myst_heading_anchors = 3
+nb_execution_mode = "off" #"auto"
+nb_execution_allow_errors = True

docs/index.rst

@@ -1,11 +1,8 @@
 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.
 
@@ -20,25 +17,45 @@ 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: 
 
 git clone https://github.com/python-accelerator-middle-layer/pyaml.git
 
 
+Documentation
+-------------
+
+.. toctree::
+    :maxdepth: 1
+    :caption: How to:
+    :glob:
+
+    Load a configuration file <notebooks/load_configuration>
+    Switch design live <notebooks/live_design>
+    Select a control system <notebooks/control_system>
+
+.. toctree::
+   :caption: Modules:
+   :maxdepth: 1
+   :glob:
+
+   modules/*
+
+
 Collaboration community
 ------------------------
 
 Discussion
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~
 
 `Mattermost <https://mattermost.hzdr.de/accelerator-middle-layer/channels/town-square>`_
 
 (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. 
 
@@ -48,23 +65,13 @@ 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
 
 
-Documentation
-----------------------
-
-.. toctree::
-   :caption: Modules
-   :maxdepth: 1
-   :glob:
-
-   modules/*
-
 
 Indices and tables
-====================================
+==================
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/notebooks/control_system.ipynb

@@ -0,0 +1,43 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7a473047",
+   "metadata": {},
+   "source": [
+    "# Control System set up"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "62672006",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyaml.pyaml import pyaml,PyAML"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/notebooks/load_configuration.ipynb

@@ -0,0 +1,124 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "420c1a3c",
+   "metadata": {},
+   "source": [
+    "# Configuration"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "7204f09a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pyaml.pyaml import pyaml,PyAML\n",
+    "\n",
+    "ml:PyAML = pyaml('../../tests/config/EBSTune.yaml')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f6ccb72a",
+   "metadata": {},
+   "source": [
+    "pyaml/tests/config/EBSTune.yaml is an example pyAML yaml configuration file that defines:\n",
+    "- a 6GeV Storage ring with\n",
+    "  - 1 array (family) of quadrupoles used for tune correction\n",
+    "  - 1 tune device\n",
+    "  - controlled by Tango\n",
+    "  - simulated with AT\n",
+    "\n",
+    "It looks like this: \n",
+    "\n",
+    "```\n",
+    "type: pyaml.pyaml\n",
+    "instruments:\n",
+    "  - type: pyaml.instrument\n",
+    "    name: sr               \n",
+    "    energy: 6e9\n",
+    "    simulators:\n",
+    "      - type: pyaml.lattice.simulator\n",
+    "        lattice: sr/lattices/ebs.mat\n",
+    "        name: design\n",
+    "    controls:\n",
+    "      - type: tango.pyaml.controlsystem\n",
+    "        tango_host: ebs-simu-3:10000\n",
+    "        name: live\n",
+    "    data_folder: /data/store\n",
+    "    arrays:\n",
+    "      - type: pyaml.arrays.magnet\n",
+    "        name: QForTune\n",
+    "        elements:\n",
+    "          - QD2E-C04\n",
+    "          - QD2A-C05\n",
+    "          - QD2E-C05\n",
+    "          - QD2A-C06\n",
+    "          - QD2E-C06\n",
+    "          - QD2A-C07\n",
+    "          - ...\n",
+    "    devices: \n",
+    "    - type: pyaml.magnet.quadrupole\n",
+    "      name: QD2A-C03\n",
+    "      model:\n",
+    "        type: pyaml.magnet.linear_model\n",
+    "        calibration_factor: 1.002096389\n",
+    "        crosstalk: 0.99912\n",
+    "        curve:\n",
+    "          type: pyaml.configuration.csvcurve\n",
+    "          file: sr/magnet_models/QD2_strength.csv\n",
+    "        unit: 1/m\n",
+    "        powerconverter:\n",
+    "          type: tango.pyaml.attribute\n",
+    "          attribute: srmag/vps-qd2/c03-a/current\n",
+    "          unit: A\n",
+    "    - ... \n",
+    "    - ...\n",
+    "    - ...\n",
+    "    - type: pyaml.diagnostics.tune_monitor\n",
+    "      name: BETATRON_TUNE\n",
+    "      tune_h:\n",
+    "        type: tango.pyaml.attribute_read_only\n",
+    "        attribute: srdiag/tune/tune_h\n",
+    "        unit: mm\n",
+    "      tune_v:\n",
+    "        type: tango.pyaml.attribute_read_only\n",
+    "        attribute: srdiag/tune/tune_v\n",
+    "        unit: mm\n",
+    "```\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0a3805fd-f96d-4ca0-9246-97b30baa1c32",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/requirements.txt

@@ -7,6 +7,9 @@ sphinxcontrib-mermaid==1.0.0
 myst-parser==4.0.0
 sphinx-hoverxref==1.4.1
 numpy==2.3.4
-pydantic==2.11.0
+pydantic==2.12.4
 accelerator-toolbox==0.7.1
-matplotlib==3.10.7
+matplotlib==3.10.7
+ipykernel==7.1.0
+myst-nb==1.3.0
+pydata-sphinx-theme==0.16.1