Tweaks to create accelerator tutorial

docs/tutorials/functionality/01_create_accelerator.py

@@ -150,22 +150,23 @@
 # Configuration files can be written in YAML or JSON. This example shows a YAML file.
 
 # %%
-# The Configuration Rule
-# ~~~~~~~~~~~~~~~~~~~~~~
-# A configuration file describes the same objects as the ones created in approach 1,
-# following one simple rule:
+# .. admonition:: The Configuration Rule
 #
-# - the ``class`` field gives the full path of the Python class to create,
-# - **every other field is an argument of the constructor of that class**, with the same name,
-# - when an argument is itself an object, its value is a nested item with its own ``class``.
+#    A configuration file describes the same objects as the ones created in approach 1,
+#    following one simple rule:
 #
-# For example, in approach 1 the quadrupole was created with:
+#    - The ``class`` field gives the full path of the Python class to create,
+#    - **Every other field is an argument of the constructor of that class** with the same
+#      name as the field and the value to pass to the constructor,
+#    - When an argument is itself an object, its value is a nested item with its own ``class`` field.
+#
+# In approach 1 the quadrupole was created with:
 #
 # .. code-block:: python
 #
 #    Quadrupole(name="QF_001", model=IdentityMagnetModel(physics=""))
 #
-# which becomes in the configuration file:
+# When writing a configuration file instead it becomes:
 #
 # .. code-block:: yaml
 #
@@ -175,24 +176,21 @@
 #      class: pyaml.magnet.identity_model.IdentityMagnetModel
 #      physics: ''
 #
-# The accepted fields of any class are therefore given by the arguments of its constructor,
-# which you can see with ``help()``. The first lines show the constructor signature, and the
+# Since the accepted fields of a class are given by the arguments of its constructor, you
+# can see them using ``help()``. The first lines show the constructor signature, and the
 # ``Parameters`` section describes each argument:
 
 help(Quadrupole)
 
 # %%
 # Write the Configuration File
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# A configuration file is a plain text file. You can write it with any text editor. Other
-# tools which can help you are described in the how-to guide
+# You can write a configuration file with any text editor.
+# More details, advice and tools that can help are described in the how-to guide
 # :doc:`Create and Load Configuration <../../how-to/configuration/create-configuration>`.
 #
-# The file below describes the same accelerator as in approach 1. Compare each item with
-# the Python code above: ``Accelerator(facility=..., machine=..., energy=..., simulators=[...],
-# devices=[...])``, ``Simulator(name=..., lattice=...)`` and ``Quadrupole(name=..., model=...)``.
-#
-# The lattice path is given by an environment variable, using the ``${env:NAME}`` syntax.
+# The file below describes the same accelerator as in approach 1. The main difference is
+# that the lattice path is given by an environment variable, using the ``${env:NAME}`` syntax.
 # It could also be written directly as an absolute path, or relative to a root directory.
 
 configuration = """\
@@ -216,8 +214,8 @@
     file.write(configuration)
 
 # %%
-# Specify the Paths
-# ~~~~~~~~~~~~~~~~~
+# Specify the Path
+# ~~~~~~~~~~~~~~~~
 # The path to the configuration file can be specified as absolute or relative to a root directory.
 
 # Set the root directory