diff --git a/docs/source/how-to/configuration/use-configuration-schema.ipynb b/docs/source/how-to/configuration/use-configuration-schema.ipynb index 1788178..4869ab3 100644 --- a/docs/source/how-to/configuration/use-configuration-schema.ipynb +++ b/docs/source/how-to/configuration/use-configuration-schema.ipynb @@ -7,7 +7,7 @@ "source": [ "# Generate Configuration Using Configuration Schemas\n", "\n", - "This guide shows how to use `ConfigurationSchema` to create a configuration." + "This guide shows how to use `ConfigurationSchema` to create a configuration. This allows to program the configuration if you prefer instead of using any of the [options based on a JSON Schema](.//create-configuration.md)." ] }, { @@ -21,7 +21,7 @@ "source": [ "## Discover Schemas\n", "\n", - "First create the registry and discover available schemas for the configuration." + "First create the registry and discover available schemas." ] }, { @@ -29,108 +29,12 @@ "execution_count": 1, "id": "e37b2c3b", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "SchemaRegistry(\n", - " 'pyaml.accelerator.Accelerator': pyaml.accelerator.AcceleratorConfigurationSchema,\n", - " 'pyaml.arrays.array.ArrayConfig': pyaml.arrays.array.ArrayConfigConfigurationSchema,\n", - " 'pyaml.arrays.bpm.BPM': pyaml.arrays.bpm.BPMConfigurationSchema,\n", - " 'pyaml.arrays.cfm_magnet.CombinedFunctionMagnet': pyaml.arrays.cfm_magnet.CombinedFunctionMagnetConfigurationSchema,\n", - " 'pyaml.arrays.element.Element': pyaml.arrays.element.ElementConfigurationSchema,\n", - " 'pyaml.arrays.magnet.Magnet': pyaml.arrays.magnet.MagnetConfigurationSchema,\n", - " 'pyaml.arrays.serialized_magnet.SerializedMagnets': pyaml.arrays.serialized_magnet.SerializedMagnetsConfigurationSchema,\n", - " 'pyaml.bpm.bpm.BPM': pyaml.bpm.bpm.BPMConfigurationSchema,\n", - " 'pyaml.common.element.Element': pyaml.common.element.ElementConfigurationSchema,\n", - " 'pyaml.common.holders.element_holder.ElementHolder': pyaml.common.holders.element_holder.ElementHolderConfigurationSchema,\n", - " 'pyaml.control.controlsystem.ControlSystem': pyaml.control.controlsystem.ControlSystemConfigurationSchema,\n", - " 'pyaml.control.deviceaccess.DeviceAccess': pyaml.control.deviceaccess.DeviceAccessConfigurationSchema,\n", - " 'pyaml.control.deviceaccesslist.DeviceAccessList': pyaml.control.deviceaccesslist.DeviceAccessListConfigurationSchema,\n", - " 'pyaml.diagnostics.atune_monitor.ABetatronTuneMonitor': pyaml.diagnostics.atune_monitor.ABetatronTuneMonitorConfigurationSchema,\n", - " 'pyaml.diagnostics.tune_monitor.BetatronTuneMonitor': pyaml.diagnostics.tune_monitor.BetatronTuneMonitorConfigurationSchema,\n", - " 'pyaml.lattice.attribute_linker.PyAtAttributeElementsLinker': pyaml.lattice.attribute_linker.PyAtAttributeElementsLinkerConfigurationSchema,\n", - " 'pyaml.lattice.lattice_elements_linker.LatticeElementsLinker': pyaml.lattice.lattice_elements_linker.LatticeElementsLinkerConfigurationSchema,\n", - " 'pyaml.lattice.lattice_elements_linker.LinkerConfigModel': pyaml.lattice.lattice_elements_linker.LinkerConfigModelConfigurationSchema,\n", - " 'pyaml.lattice.simulator.Simulator': pyaml.lattice.simulator.SimulatorConfigurationSchema,\n", - " 'pyaml.magnet.cfm_magnet.CombinedFunctionMagnet': pyaml.magnet.cfm_magnet.CombinedFunctionMagnetConfigurationSchema,\n", - " 'pyaml.magnet.csvcurve.CSVCurve': pyaml.magnet.csvcurve.CSVCurveConfigurationSchema,\n", - " 'pyaml.magnet.csvmatrix.CSVMatrix': pyaml.magnet.csvmatrix.CSVMatrixConfigurationSchema,\n", - " 'pyaml.magnet.curve.Curve': pyaml.magnet.curve.CurveConfigurationSchema,\n", - " 'pyaml.magnet.hcorrector.HCorrector': pyaml.magnet.hcorrector.HCorrectorConfigurationSchema,\n", - " 'pyaml.magnet.identity_cfm_model.IdentityCFMagnetModel': pyaml.magnet.identity_cfm_model.IdentityCFMagnetModelConfigurationSchema,\n", - " 'pyaml.magnet.identity_model.IdentityMagnetModel': pyaml.magnet.identity_model.IdentityMagnetModelConfigurationSchema,\n", - " 'pyaml.magnet.inline_curve.InlineCurve': pyaml.magnet.inline_curve.InlineCurveConfigurationSchema,\n", - " 'pyaml.magnet.inline_matrix.InlineMatrix': pyaml.magnet.inline_matrix.InlineMatrixConfigurationSchema,\n", - " 'pyaml.magnet.linear_cfm_model.LinearCFMagnetModel': pyaml.magnet.linear_cfm_model.LinearCFMagnetModelConfigurationSchema,\n", - " 'pyaml.magnet.linear_model.LinearMagnetModel': pyaml.magnet.linear_model.LinearMagnetModelConfigurationSchema,\n", - " 'pyaml.magnet.linear_serialized_model.LinearSerializedMagnetModel': pyaml.magnet.linear_serialized_model.LinearSerializedMagnetModelConfigurationSchema,\n", - " 'pyaml.magnet.magnet.Magnet': pyaml.magnet.magnet.MagnetConfigurationSchema,\n", - " 'pyaml.magnet.matrix.Matrix': pyaml.magnet.matrix.MatrixConfigurationSchema,\n", - " 'pyaml.magnet.model.MagnetModel': pyaml.magnet.model.MagnetModelConfigurationSchema,\n", - " 'pyaml.magnet.octupole.Octupole': pyaml.magnet.octupole.OctupoleConfigurationSchema,\n", - " 'pyaml.magnet.quadrupole.Quadrupole': pyaml.magnet.quadrupole.QuadrupoleConfigurationSchema,\n", - " 'pyaml.magnet.serialized_magnet.SerializedMagnets': pyaml.magnet.serialized_magnet.SerializedMagnetsConfigurationSchema,\n", - " 'pyaml.magnet.sextupole.Sextupole': pyaml.magnet.sextupole.SextupoleConfigurationSchema,\n", - " 'pyaml.magnet.skewoctu.SkewOctu': pyaml.magnet.skewoctu.SkewOctuConfigurationSchema,\n", - " 'pyaml.magnet.skewquad.SkewQuad': pyaml.magnet.skewquad.SkewQuadConfigurationSchema,\n", - " 'pyaml.magnet.skewsext.SkewSext': pyaml.magnet.skewsext.SkewSextConfigurationSchema,\n", - " 'pyaml.magnet.spline_model.SplineMagnetModel': pyaml.magnet.spline_model.SplineMagnetModelConfigurationSchema,\n", - " 'pyaml.magnet.vcorrector.VCorrector': pyaml.magnet.vcorrector.VCorrectorConfigurationSchema,\n", - " 'pyaml.rf.rf_plant.RFPlant': pyaml.rf.rf_plant.RFPlantConfigurationSchema,\n", - " 'pyaml.rf.rf_transmitter.RFTransmitter': pyaml.rf.rf_transmitter.RFTransmitterConfigurationSchema,\n", - " 'pyaml.tuning_tools.bba.BBA': pyaml.tuning_tools.bba.BBAConfigurationSchema,\n", - " 'pyaml.tuning_tools.bba2.BBA2': pyaml.tuning_tools.bba2.BBA2ConfigurationSchema,\n", - " 'pyaml.tuning_tools.chromaticity.Chromaticity': pyaml.tuning_tools.chromaticity.ChromaticityConfigurationSchema,\n", - " 'pyaml.tuning_tools.chromaticity_monitor.ChromaticityMonitor': pyaml.tuning_tools.chromaticity_monitor.ChromaticityMonitorConfigurationSchema,\n", - " 'pyaml.tuning_tools.chromaticity_response_matrix.ChromaticityResponseMatrix': pyaml.tuning_tools.chromaticity_response_matrix.ChromaticityResponseMatrixConfigurationSchema,\n", - " 'pyaml.tuning_tools.dispersion.Dispersion': pyaml.tuning_tools.dispersion.DispersionConfigurationSchema,\n", - " 'pyaml.tuning_tools.measurement_tool.MeasurementTool': pyaml.tuning_tools.measurement_tool.MeasurementToolConfigurationSchema,\n", - " 'pyaml.tuning_tools.orbit.Orbit': pyaml.tuning_tools.orbit.OrbitConfigurationSchema,\n", - " 'pyaml.tuning_tools.orbit_response_matrix.OrbitResponseMatrix': pyaml.tuning_tools.orbit_response_matrix.OrbitResponseMatrixConfigurationSchema,\n", - " 'pyaml.tuning_tools.orbit_response_matrix_data.OrbitResponseMatrixData': pyaml.tuning_tools.orbit_response_matrix_data.OrbitResponseMatrixDataConfigurationSchema,\n", - " 'pyaml.tuning_tools.response_matrix_data.ResponseMatrixData': pyaml.tuning_tools.response_matrix_data.ResponseMatrixDataConfigurationSchema,\n", - " 'pyaml.tuning_tools.tune.Tune': pyaml.tuning_tools.tune.TuneConfigurationSchema,\n", - " 'pyaml.tuning_tools.tune_response_matrix.TuneResponseMatrix': pyaml.tuning_tools.tune_response_matrix.TuneResponseMatrixConfigurationSchema,\n", - " 'pyaml.tuning_tools.tuning_tool.TuningTool': pyaml.tuning_tools.tuning_tool.TuningToolConfigurationSchema,\n", - " 'pyaml.validation.validation_models.DynamicValidation': pyaml.validation.validation_models.DynamicValidationConfigurationSchema,\n", - " 'pyaml_cs_oa.catalog.Catalog': pyaml_cs_oa.catalog.CatalogConfigurationSchema,\n", - " 'pyaml_cs_oa.controlsystem.OphydAsyncControlSystem': pyaml_cs_oa.controlsystem.OphydAsyncControlSystemConfigurationSchema,\n", - " 'pyaml_cs_oa.dynamic_catalog.DynamicCatalog': pyaml_cs_oa.dynamic_catalog.DynamicCatalogConfigurationSchema,\n", - " 'pyaml_cs_oa.epicsR.EpicsR': pyaml_cs_oa.epicsR.EpicsRConfigurationSchema,\n", - " 'pyaml_cs_oa.epicsRW.EpicsRW': pyaml_cs_oa.epicsRW.EpicsRWConfigurationSchema,\n", - " 'pyaml_cs_oa.epicsW.EpicsW': pyaml_cs_oa.epicsW.EpicsWConfigurationSchema,\n", - " 'pyaml_cs_oa.float_signal.FloatSignalContainer': pyaml_cs_oa.float_signal.FloatSignalContainerConfigurationSchema,\n", - " 'pyaml_cs_oa.signal.OASignal': pyaml_cs_oa.signal.OASignalConfigurationSchema,\n", - " 'pyaml_cs_oa.static_catalog.StaticCatalog': pyaml_cs_oa.static_catalog.StaticCatalogConfigurationSchema,\n", - " 'pyaml_cs_oa.static_catalog_entry.StaticCatalogEntry': pyaml_cs_oa.static_catalog_entry.StaticCatalogEntryConfigurationSchema,\n", - " 'pyaml_cs_oa.tangoAtt.TangoAtt': pyaml_cs_oa.tangoAtt.TangoAttConfigurationSchema,\n", - " 'pyaml_cs_oa.types.EpicsConfigR': pyaml_cs_oa.types.EpicsConfigRConfigurationSchema,\n", - " 'pyaml_cs_oa.types.EpicsConfigRW': pyaml_cs_oa.types.EpicsConfigRWConfigurationSchema,\n", - " 'pyaml_cs_oa.types.EpicsConfigW': pyaml_cs_oa.types.EpicsConfigWConfigurationSchema,\n", - " 'pyaml_cs_oa.types.TangoConfigAtt': pyaml_cs_oa.types.TangoConfigAttConfigurationSchema,\n", - " 'tango.pyaml.attribute.Attribute': tango.pyaml.attribute.AttributeConfigurationSchema,\n", - " 'tango.pyaml.attribute_list.AttributeList': tango.pyaml.attribute_list.AttributeListConfigurationSchema,\n", - " 'tango.pyaml.attribute_list_read_only.AttributeListReadOnly': tango.pyaml.attribute_list_read_only.AttributeListReadOnlyConfigurationSchema,\n", - " 'tango.pyaml.attribute_read_only.AttributeReadOnly': tango.pyaml.attribute_read_only.AttributeReadOnlyConfigurationSchema,\n", - " 'tango.pyaml.catalog.Catalog': tango.pyaml.catalog.CatalogConfigurationSchema,\n", - " 'tango.pyaml.controlsystem.TangoControlSystem': tango.pyaml.controlsystem.TangoControlSystemConfigurationSchema,\n", - " 'tango.pyaml.initializable_element.InitializableElement': tango.pyaml.initializable_element.InitializableElementConfigurationSchema,\n", - " 'tango.pyaml.multi_attribute.MultiAttribute': tango.pyaml.multi_attribute.MultiAttributeConfigurationSchema,\n", - " 'tango.pyaml.static_catalog.StaticCatalog': tango.pyaml.static_catalog.StaticCatalogConfigurationSchema,\n", - " 'tango.pyaml.static_catalog_entry.StaticCatalogEntry': tango.pyaml.static_catalog_entry.StaticCatalogEntryConfigurationSchema,\n", - " 'tango.pyaml.tango_catalog.TangoCatalog': tango.pyaml.tango_catalog.TangoCatalogConfigurationSchema,\n", - ")\n" - ] - } - ], + "outputs": [], "source": [ "from pyaml.validation import SchemaRegistry\n", "\n", "registry = SchemaRegistry()\n", - "registry.discover()\n", - "print(registry)" + "registry.discover()" ] }, { @@ -142,7 +46,7 @@ "\n", "To create a configuration for an accelerator start by extracting the schema for it from the registry. You can see the required fields and their description using `describe()`.\n", "\n", - "Unfortunately static type checking does not work if the schema is generated dynamically." + "Unfortunately static type checking does not work since the schema is generated dynamically." ] }, { @@ -257,7 +161,7 @@ "id": "6a8e0a65", "metadata": {}, "source": [ - "In this way you can program the configuration. Since `ConfigurationSchema` inherits from Pydantic `BaseModel` the configuration is validated for each object you create." + "Since `ConfigurationSchema` inherits from [Pydantic BaseModel](https://pydantic.dev/docs/validation/latest/concepts/models/) the configuration is validated for each object you create, meaning you can validate the configuration step-by-step instead of validating the whole nested structure in one step." ] }, { diff --git a/docs/source/how-to/configuration/use-meta-configurator.md b/docs/source/how-to/configuration/use-meta-configurator.md index 8367a1b..49e8126 100644 --- a/docs/source/how-to/configuration/use-meta-configurator.md +++ b/docs/source/how-to/configuration/use-meta-configurator.md @@ -30,10 +30,10 @@ In this guide we will focus on the data page but there is also a lot of other fu On the data page, the editor has two areas: -- **Text view** (on the left): shows and edits the json or yaml document. +- **Text view** (on the left): shows and edits the JSON or YAML document. - **GUI view** (on the right): presents the document as a form generated from the loaded schema. Here you can add values and choose options in a menu. -The GUI View is convenient for knowing which fields exist and their required types. The Text View is useful for checking the final structure and for switching between supported formats. +The GUI view is convenient for knowing which fields exist and their required types. The Text view is useful for checking the final structure and for switching between supported formats. ## Load the Schema diff --git a/docs/source/how-to/configuration/use-vscode-json-schema.md b/docs/source/how-to/configuration/use-vscode-json-schema.md index e18b3c0..c3878ce 100644 --- a/docs/source/how-to/configuration/use-vscode-json-schema.md +++ b/docs/source/how-to/configuration/use-vscode-json-schema.md @@ -8,7 +8,7 @@ This guide shows how to associate a JSON Schema with JSON and YAML files and use - **JSON**: JSON support is built into VS Code. JSON files are recognized automatically when their names end in `.json`. -- **YAML**: For YAML you need to install an extension. Open the `Extensions` view, search for `YAML`, and install the extension published by Red Hat. +- **YAML**: For YAML you need to install an extension. Open the `Extensions` view, search for `YAML` and install the extension published by Red Hat. ## Enable Remote Schema Downloads @@ -36,9 +36,9 @@ The examples use the accelerator schema published in [pyaml-schemas](https://git # yaml-language-server: $schema=https://raw.githubusercontent.com/python-accelerator-middle-layer/pyaml-schemas/main/schemas/accelerator.schema.json ``` -## Edit the file +## Edit the File -VS Code should now provide code completion when you type a property name. Hover over a property to see its description and red or yellow squiggles show when a value does not match the schema. +VS Code should now provide code completion when you type a property name. Hover over a property to see its description and red or yellow squiggles should show when a value does not match the schema. The way the completion looks and works is slightly different between JSON and YAML.