Conversation
- Add explanation pages: "What is pyAML?", "pyAML Structure" (with an object hierarchy diagram) and "Control Modes" (with planned modes). - State the "one field = one constructor argument" rule in the configuration explanation, and fix a broken link and an unclosed block. - Rewrite the "Create and Load Configuration" how-to around writing a YAML file by hand. - Add tutorial 00 (concepts, how to run the tutorials locally, learning path); introduce the test lattice in tutorials 01 and 02; use class: paths and help() in the tutorials. - Enable MyST definition lists and heading anchors. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… is an focus the list on features that are new in pyAML.
|
Very nice! I have started to review it. I think I will do it page for page and make separate PRs into this branch with my suggestions so it doesn't become too much to review in one go. |
…l-structure Add that the test lattice is also used for integration tests.
…-is-pyaml Updates to what is pyAML
…rol-modes Change that all measurements behave in the same way to similar way.
…sary Mark pyAT as a name as for other names.
…nd the value to be passed.
…ts of codes at the same time.
…tion is turned on and not a general requirement for the configuration.
…kages and not only pyaml.
|
I have almost finished the review of the explanations and how-to guides. I only want to write a suggestion for how to modify the control modes section. I'm on leave today so have to look at the tutorials next week. |
…-glossary Move glossary to main menu.
Tweaks to the explanation of the catalog
…iguration-explanation Tweaks to the configuration explanation
|
For the tutorial, I plan to update them once this python-accelerator-middle-layer/pyaml#430 has been merged |
|
I have reviewed the whole PR now and made PRs for the modifications I suggest. From my side it is just merging those PRs and potentially a split up of the page for creating the configuration needed before merging it. For me the split up of the create configuration page can also be done as a second PR after this merge since this version already makes the documentation much better. |
This branch has not been deployed
2 participants
This PR aims to resolves #36 #38 #39 #26
It adds introductory material for new users and mostly rewrites the configuration docs. I tried to include the feedback we had from the recent configuration hackathon so it's better for people from outside the project.
It introduces larges changes to the current documentation so please check it and see if you agree with the changes.
FYI, it's a mix between AI generated doc and human made. It was very helpful to generate the code examples and check that it's really working.
Any further changes which help to add more information and clarity is of course welcome.
New explanation pages
explanation/about.md): why pyAML is a middle layer, the project goals, the layers of the project (core, shared applications, facility-specific applications) and the guiding principles of the configuration.explanation/architecture.md): how the layers map to Python packages and objects, with a diagram of the object hierarchy.explanation/control-modes.md): theliveanddesignmodes, their shared interface, and the modes that are planned.explanation/glossary.md): definitions of the main pyAML terms.Updated explanations
class:syntax.How-to
help(), how to build the file step by step, splitting it into several files, using your own classes, validation, and tools that help write the file.Tutorials
_static/fodo-cell.svg). It explains the configuration rule by comparing the Python constructor with its YAML version, useshelp()to find the fields, and shows that a misspelled field is rejected when the file is loaded.keys(),has()andavailability(), getting an object, and searching element names.tutorials/config.yaml,functionality/config.yaml) now useclass:paths instead oftype:.