Hla 1142 module creation docs - #77
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #77 +/- ##
=======================================
Coverage 99.48% 99.48%
=======================================
Files 27 27
Lines 979 979
=======================================
Hits 974 974
Misses 5 5 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
| <name>/<version>.yaml one file per Module version | ||
| ├── deprecated: false lifecycle flag | ||
| └── module | ||
| ├── name / version / description |
There was a problem hiding this comment.
Shouldnt these be on seperate lines?
| └── applications one or more, each of: | ||
| ├── apptainer container image + entrypoints | ||
| ├── shell a bash script | ||
| └── binary a downloaded, hash-checked executable |
There was a problem hiding this comment.
The description text should probably be spaced in the same way for all of the options, for apptainer, shell and binary the space between option and description is smaller
There was a problem hiding this comment.
Link to application types section below?
|
|
||
| ## A Module | ||
|
|
||
| A Module is the unit an end user loads. Alongside its `name` and `version` it carries: |
There was a problem hiding this comment.
Are the name and version just excluded from the table for brevity?
| | `allow_updates` | Permit in-place changes to this version — see [the guard rails](deprecation-lifecycle.md#the-guard-rails). | | ||
| | `exclude_from_defaults` | Keep this version out of automatic default selection — see [default versions](default-versions.md#excluding-a-version-from-the-automatic-default). | | ||
|
|
||
| `load_script` and `unload_script` run extra commands when the Module is loaded and |
There was a problem hiding this comment.
Are load_script and load_script also Module config options? It doesnt explicitly say what they are or where/if they are configured, it just says they are run when the Module is loaded.
I think its a bit confusing because I might expect all of the options to be in the table, even the obvious or not recommended for general use options.
| Every entry under `applications` sets `app_type` to select one of three kinds; a single | ||
| Module can mix them. | ||
|
|
||
| | `app_type` | Provides | Key fields | |
There was a problem hiding this comment.
Why does this table use Key fields instead of just fields? If its because it only contains a subset of fields, then shouldnt the table also use Key fields as it is also a subset of fields.
|
|
||
| **Apptainer** uses one container image with one or more `entrypoints`, each mapping an | ||
| executable name to a command run inside the container. Options — container `mounts`, | ||
| `command_args`, `apptainer_args`, `host_binaries` — can be set per entrypoint or shared |
There was a problem hiding this comment.
Why are these fields documented in prose here and not in either the tree diagram at the top or their own table? I see that some of them are documented in the second table, but not all, it just seems a bit inconsistent to me.
| ```{literalinclude} ../../src/deploy_tools/demo_configuration/settings.yaml | ||
| :language: yaml | ||
| :lines: 3- | ||
| ``` |
There was a problem hiding this comment.
All of these sections look broken in github MD preview, but I assume they work in the generated docs?
| @@ -0,0 +1,78 @@ | |||
| # Write a Module configuration | |||
|
|
|||
| To add or change a Module you edit YAML in the configuration folder. This guide covers the | |||
| repository-wide instead of per file): | ||
|
|
||
| ```yaml | ||
| # yaml-language-server: $schema=https://raw.githubusercontent.com/DiamondLightSource/deploy-tools/main/src/deploy_tools/models/schemas/release.json |
There was a problem hiding this comment.
Is this line only for vscode or does it work for other editors?
| You don't run `deploy-tools` yourself. Open a merge request in the configuration | ||
| repository; CI validates the change and, once it is merged, deploys it (see | ||
| [drive deploy-tools from CI](ci-pipeline.md)). The `yaml-language-server` schema line | ||
| catches structural mistakes in your editor as you type, before you open the request. | ||
|
|
There was a problem hiding this comment.
Remember that this documentation is for anyone using deploy-tools. While we don't recommend using deploy-tools manually, someone else using deploy-tools may choose to use it that way. Also maybe "in your configuration repository" rather than "in the configuration repository" would make more sense? And maybe change the text to say "see [drive deploy-tools from CI] for a guide on setting up your configuration repository."
2 participants
Adds documentation on how to create a deploy-tools Module.