Documentation for creating configuration

[TeresiaOlsson]

I have added documentation for how to create the documentation and a page which is intended as the entry point for all those pages.

This is the one: https://python-accelerator-middle-layer.github.io/documentation/how-to/configuration/create-configuration.html

@simoneliuzzo Can you perhaps take a look and see what you think about it?

I know that the option to use the ConfigurationSchemas directly for those who wish to program the configuration isn't working perfectly yet. There are some steps which I think can be made more user-friendly by adding additional methods in the schema registry.

The two methods using the JSON Schema I found to be somewhat easier to use. Also not perfect and there are things that can be improved to make it more user-friendly but perhaps that is already an indication that the JSON Schema option is the direction to go for when we have time to make our own GUI application for the configuration.

[simoneliuzzo]

Dear Teresia, I am looking at the page to create configurations The following block is a bit oscure to me. May be it should be wrapped in a pyaml registry method? For the subschemas, you can list available subclasses that are available in the registry. control_system_schema = registry["pyaml.control.controlsystem.ControlSystem"] control_system_options = { class_path: schema for class_path, schema in registry.items() if schema is not control_system_schema and ( issubclass(schema, control_system_schema) or schema.is_virtual_subclass_of(control_system_schema) ) } for class_path, schema in sorted(control_system_options.items()): print(class_path, "→", schema.__name__) I clicked the first link in the page “Use ConfigurationSchema” and somehow I skipped the first 3 pages I should have red (“Schema registry", "validate configuration" and "Generate Json schemas”). May be a small sentence pointing to these pages as preliminary reading? Or may be this is intentional as the 3 pages are meant for developers?  In general the description is very complete and show large flexibility in generating the configuration. Some pages ("Use the Schema registry” for example) are guides at developer level. This is very good and needed for the documentation, in my opinion. In page "Validate Configuration”, I would add a sentence about why validating is necessary. Something like: “To make sure your configuration follows the pyAML requirements, pyAML implements validation for your configuration file. If something is wrong pyAML will thus be able to point out what is wrong to let you fix it". In page "Generate JSON Schemas”, the schema block does not show in the column. For the future may be we could find a way to make it visible.  The (rather scary big) schema is just for a quadrupole, if I understand well. It could be stated in the page with a sentence such as (if it is true): “ The following example illustrate the schema for a quadrupole. The schema collects all possible options available in pyAML for a quadrupole. Schemas are not exposed directly to users ( that use instead … and … ) but are a powerful tool for developers." In use configuration schemas page <https://python-accelerator-middle-layer.github.io/documentation/how-to/configuration/use-configuration-schema.html> I would add at the bottom a small reminder on how to use the file generated. It is already explained in the main page, but having it repeated here, could help the readers. An issues I see is a rather steep entry point for new users. The new users would need to read several pages of code before starting to use pyaml for their own accelerator. I will try to produce a python script to get a configuration starting from a pyAT file. If I make it in time, I will propose to add this option among the ways to generate configuration files. Thank you! best regards Simone On 13 Sep 2026, at 21:06, Teresia Olsson ***@***.***> wrote: TeresiaOlsson created an issue (python-accelerator-middle-layer/documentation#26) <#26> I have added documentation for how to create the documentation and a page which is intended as the entry point for all those pages. This is the one: https://python-accelerator-middle-layer.github.io/documentation/how-to/configuration/create-configuration.html @simoneliuzzo <https://github.com/simoneliuzzo> Can you perhaps take a look and see what you think about it? I know that the option to use the ConfigurationSchemas directly for those who wish to program the configuration isn't working perfectly yet. There are some steps which I think can be made more user-friendly by adding additional methods in the schema registry. The two methods using the JSON Schema I found to be somewhat easier to use. Also not perfect and there are things that can be improved to make it more user-friendly but perhaps that is already an indication that the JSON Schema option is the direction to go for when we have time to make our own GUI application for the configuration. — Reply to this email directly, view it on GitHub <#26?email_source=notifications&email_token=AHHP4VVQ4WFFNSLWMS4U5E35O3V3DA5CNFSL4Z3JMQ5C6L3HNF2C22DVMIXUS43TOVSS6NJUGQZDCMRXHA3TRJTSMVQXG33OU5WWK3TUNFXW5JLFOZSW45FMMZXW65DFOJPWG3DJMNVQ>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHHP4VQWA2MZ7UEJWQYSWET5O3V3DAVCNFSNUABGKJSXA33TNF2G64TZHMYTGMBYGU3TCOBSHE5US43TOVSTWNJUGQZDCMRXHA3TRILWAI>. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AHHP4VUVOJMLNFOO36OJQYL5O3V3DA5CNFSL4Z3JMQ5C6L3HNF2C22DVMIXUS43TOVSS6NJUGQZDCMRXHA3TRJTSMVQXG33OU5WWK3TUNFXW5JLFOZSW45FKMZXW65DFOJPWS33T> and Android <https://github.com/notifications/mobile/android/AHHP4VQJBO4M4YWWXQUDI2D5O3V3DA5CNFSL4Z3JMQ5C6L3HNF2C22DVMIXUS43TOVSS6NJUGQZDCMRXHA3TRJTSMVQXG33OU5WWK3TUNFXW5JLFOZSW45FOMZXW65DFOJPWC3TEOJXWSZA>. Download it today! You are receiving this because you were mentioned.

[TeresiaOlsson]

Dear Teresia,

I am looking at the page to create configurations

The following block is a bit oscure to me. May be it should be wrapped in a pyaml registry method?
For the subschemas, you can list available subclasses that are available in the registry.

control_system_schema = registry["pyaml.control.controlsystem.ControlSystem"]

control_system_options = {
class_path: schema
for class_path, schema in registry.items()
if schema is not control_system_schema
and (
issubclass(schema, control_system_schema)
or schema.is_virtual_subclass_of(control_system_schema)
)
}

for class_path, schema in sorted(control_system_options.items()):
print(class_path, "→", schema.name)

Yes, this I also found. I'm planning to add a method for it.

I clicked the first link in the page “Use ConfigurationSchema” and somehow I skipped the first 3 pages I should have red (“Schema registry", "validate configuration" and "Generate Json schemas”). May be a small sentence pointing to these pages as preliminary reading? Or may be this is intentional as the 3 pages are meant for developers?


They should be skipped. The how-to-guides are not arranged according to any reading order. You are supposed to go there, find the page which most describe the task you want to do and then on that page there should be links to other pages if needed.

In general the description is very complete and show large flexibility in generating the configuration. Some pages ("Use the Schema registry” for example) are guides at developer level. This is very good and needed for the documentation, in my opinion.

In page "Validate Configuration”, I would add a sentence about why validating is necessary. Something like: “To make sure your configuration follows the pyAML requirements, pyAML implements validation for your configuration file. If something is wrong pyAML will thus be able to point out what is wrong to let you fix it".

True. I will add that.

In page "Generate JSON Schemas”, the schema block does not show in the column. For the future may be we could find a way to make it visible.


I'm not sure about this? There is a scroll bar at the bottom which allows to see the whole block? But the scroll bar isn't great... I will see if I can change it. I think it can be output using shorter lines.

The (rather scary big) schema is just for a quadrupole, if I understand well. It could be stated in the page with a sentence such as (if it is true): “ The following example illustrate the schema for a quadrupole. The schema collects all possible options available in pyAML for a quadrupole. Schemas are not exposed directly to users ( that use instead … and … ) but are a powerful tool for developers."

Yes, it is. Maybe I should add some more details to explain what a JSON Schema is and how it's supposed to be used. I think it is for users but it is not meant to be read directly by a human. Only by different tools which uses JSON Schema to provide help functions for the human.

In use configuration schemas page https://python-accelerator-middle-layer.github.io/documentation/how-to/configuration/use-configuration-schema.html I would add at the bottom a small reminder on how to use the file generated. It is already explained in the main page, but having it repeated here, could help the readers.

I will add that.

An issues I see is a rather steep entry point for new users. The new users would need to read several pages of code before starting to use pyaml for their own accelerator.

I will try to produce a python script to get a configuration starting from a pyAT file. If I make it in time, I will propose to add this option among the ways to generate configuration files.

I was thinking yesterday to perhaps add something about the use of AI tools. Considering that I use AI to write the base for this documentation I think it should be possible to just give an AI assistant a pyAT lattice and the JSON schema and it can generate the configuration for you. I have the feeling that it might be the easiest of all options. But I haven't tested it yet.

[TeresiaOlsson]

I went through all the how-to guides for the configuration and hope they have become somewhat better. I also added something about using AI tools on the entry page for how to create the configuration: https://python-accelerator-middle-layer.github.io/documentation/how-to/configuration/create-configuration.html