diff --git a/docs/tutorials/functionality/00_introduction.py b/docs/tutorials/functionality/00_introduction.py index 69e659c..8615b93 100644 --- a/docs/tutorials/functionality/00_introduction.py +++ b/docs/tutorials/functionality/00_introduction.py @@ -57,31 +57,31 @@ # # - **Accelerator**: the top-level object describing one machine. It is created from a # configuration. -# - **Control mode**: one way of accessing the accelerator. ``accelerator.live`` talks to the -# control system (the real machine or a virtual accelerator), ``accelerator.design`` talks +# - **Control mode**: one way of accessing the accelerator. In the figure above ``accelerator.live`` talks to the +# a control system and ``accelerator.design`` talks # to a simulation of the machine made with `pyAT `_. # Both provide exactly the same interface. -# - **Element**: one object of the machine, such as a magnet, a BPM or the RF plant. +# - **Element**: one object of the machine, such as a magnet, a BPM or a RF cavity. # - **Array**: a named group of elements which can be read or set in one call, such as all # the BPMs. # - **Attribute**: a value of an element that can be read with ``get()`` and written # with ``set()``, such as the ``strength`` of a magnet. -# - **Configuration**: a YAML or JSON file describing all of the above. Each item of the +# - **Configuration**: a structure (most commonly a YAML or JSON file) describing all of the above. Each item of the # configuration names a Python class with its ``class`` field, and **each other field is an # argument of that class's constructor**. This rule is explored in the first tutorial. # # See :doc:`pyAML Structure <../../explanation/architecture>` and # :doc:`Control Modes <../../explanation/control-modes>` for more details, and the -# :doc:`Glossary <../../explanation/glossary>` for the definitions of the terms used in pyAML. +# :doc:`Glossary <../../glossary>` for the definitions of the terms used in pyAML. # %% # How the Tutorials Work # ---------------------- # -# **Running the tutorials.** Each tutorial can be run in the cloud with -# `Binder `_ using the launcher on its page, with nothing to install, -# or downloaded and run on your own computer, as a Jupyter notebook or a Python script -# (see below). +# **Running the tutorials.** Each tutorial can be run in the cloud without requiring +# to install or download anything by using the `Binder `_ launcher +# on the tutorial page or as a Jupyter notebook or a Python script on your own computer +# (see below for instructions). # # **The test machine.** The tutorials use a small test storage ring, with its lattice and # ready-made pyAML configurations, provided by the ``pyaml-test-lattice`` package. It is @@ -103,54 +103,42 @@ # # You need Python 3.11 or newer. Always install in a virtual environment, to avoid breaking # your Python installation (see :doc:`New to Python <../../how-to/getting-started/python-basics>` -# if you are not familiar with virtual environments). Then install: +# if you are not familiar with virtual environments). Then do: +# +# 1. Install the requirements for the tutorials # -# .. code-block:: bash +# .. code-block:: bash # -# pip install "accelerator-middle-layer[cs-oa-tango]" pyaml-test-lattice jupyterlab +# pip install -r https://raw.githubusercontent.com/python-accelerator-middle-layer/documentation/main/binder/requirements.txt # -# This installs: +# 2. [Optional] If you want to run as notebooks, install JupyterLab # -# - ``accelerator-middle-layer``: the ``pyaml`` core package. It also installs pyAT, used by -# the ``design`` control mode, together with numpy and matplotlib. -# - ``[cs-oa-tango]``: the ``pyaml-cs-oa`` control-system bindings for TANGO. The ready-made -# configurations of the test machine declare a ``live`` control mode using these bindings, -# so they are needed to load them, even if you only use the ``design`` control mode. -# - ``pyaml-test-lattice``: the test machine, with its lattice and pyAML configurations. -# - ``jupyterlab``: to open the tutorials as notebooks. It is not needed to run them as -# Python scripts. +# .. code-block:: bash # -# The other control-system bindings (``cs-oa-epics``, ``tango-pyaml``) are only needed to -# connect to your own control system, see -# :doc:`User Installation <../../how-to/installation/user-installation>`. To get exactly the -# same environment as on Binder, install the -# `Binder requirements `_ -# instead: ``pip install -r binder/requirements.txt`` from a clone of the documentation -# repository. +# pip install jupyterlab # -# Finally, download a tutorial as a notebook or a Python script with the download links in -# the right sidebar of its page, and run it with ``jupyter lab`` or ``python``. +# Finally, download a tutorial as a notebook or a Python script using the download link in +# the right sidebar of the tutorial's page, and run it with ``jupyter lab`` or ``python``. +# You can also download all tutorials in one go on the :doc:`Tutorials <../index>` main page. # %% # Where to Go Next # ---------------- +# +# There are two type of tutorials: # -# The tutorials are designed to be followed in this order: -# -# 1. :doc:`Create an Accelerator <01_create_accelerator>`: create an accelerator -# interactively and from a configuration file, and learn how the configuration maps to -# Python classes. -# 2. :doc:`Inspect an Accelerator <02_inspect_accelerator>`: explore what a complete -# accelerator configuration contains. -# 3. The **use cases**, which apply pyAML to real tasks: -# :doc:`tune correction <../use_cases/tune-correction>`, -# :doc:`orbit correction <../use_cases/orbit_correction>` and -# :doc:`chromaticity measurement <../use_cases/chromaticity-measurement>`. -# -# For more background, read the explanations: -# :doc:`What is pyAML? <../../explanation/about>`, -# :doc:`pyAML Structure <../../explanation/architecture>`, -# :doc:`Control Modes <../../explanation/control-modes>` and -# :doc:`Configuration Structure and Syntax <../../explanation/configuration>`. +# 1. **Functionality**: These cover the functionality of pyAML. +# +# 2. **Use cases**: These apply pyAML to real tasks. +# +# The tutorials are designed to first follow the functionality and then the use cases +# but they can also be run independently depending on your interests. +# +# For more background, read the explanations: +# +# - :doc:`What is pyAML? <../../explanation/about>` +# - :doc:`pyAML Structure <../../explanation/architecture>` +# - :doc:`Control Modes <../../explanation/control-modes>` +# - :doc:`Configuration Structure and Syntax <../../explanation/configuration>` # sphinx_gallery_thumbnail_path = '_static/pyaml-hierarchy.svg'