Hla 1093 jsonschema docs#58
Conversation
Under nitpicky mode with default_role='any', backticked terms in docstrings are treated as cross-references that must resolve.
The autosummary tables list every public function/class/exception, but automodule :members: only documents those with a docstring, leaving dangling :py:obj: references for the rest.
Using list[Annotated[str, StringConstraints(...)]] confuses Sphinx's annotation parser. Extract a named 'type MountPoint' alias so the field renders as list[MountPoint], and add a matching nitpick_ignore entry.
sphinx-jsonschema only outputs .rst. Without this, links fail to work between objects.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #58 +/- ##
==========================================
- Coverage 75.64% 75.51% -0.14%
==========================================
Files 25 25
Lines 936 931 -5
==========================================
- Hits 708 703 -5
Misses 228 228 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
ptsOSL
left a comment
ptsOSL
left a comment
There was a problem hiding this comment.
I would like a link to the Schemas docs somewhere more prominent in the docs. Perhaps in a new tutorial describing how to use deploy-tools?
In Reference -> Schemas -> DeploymentSettings what is additionalProperties? It is not clear from the docs. Is it just saying that there are no additional properties for a configuration option? If so then this seems a bit pointless and potentially confusing
Reference -> Schemas -> Deployment -> ApptainerApp -> global_options. The default is set to apptainer_args, but I thought the default was no extra global_options?
Reference -> Schemas -> Deployment -> EntpointOptions -> mounts -> type. Says array, but the description says list. Also true for host_binaries -> type and elsewhere.
Reference -> Schemas -> Deployment -> DefaultVersionsByName. Confused as to what this configuration is.
This duplicates content in Release and DeploymentSettings, so may be confusing.
This is used to indicate that only the given properties are valid. This can cause confusion since it is displayed identically to other properties.
|
Unfortunately, a lot of these issues just aren't easy to resolve with the only Sphinx JSON Schema plugin I can find. Let me know if the documentation is more confusing than it's worth, and we can skip this. I have also removed the Deployment documentation, since it just combines the Releases and DeploymentSettings, and is otherwise potentially confusing.
The purpose of this task was just to add the schema docs, and Reference is the correct location (as with the API docs). I'm planning to flesh out the tutorials & other sections later on, and I'll try to add any links where appropriate.
It is saying that additional properties are not allowed in valid configuration, and is a standard property in JSON Schema. I have followed Michael's advice and hidden it.
The default is set to the entire block, and is apparently how the schema generation handles
It is only an 'array' in JSON Schema, which is used in the VSCode editor and the schema docs. Unfortunately, 'list' is the correct term for yaml, and I cannot override the sphinx plugin to fix this.
This appears to be how the jsonschema plugin handles type aliases. Again, not sure what I can do here. |
3 participants
This adds docs for the generated schemas, and fixes several issues that were blocking a successful docs build. We have also added autogenerated Typer docstrings for the CLI.
As part of this, there is now a clearer separation between "public" and "internal" which is indicated with a leading underscore. This allows us to keep the published docs restricted to the most important functions etc.
Since it causes issues with the docs generation, regexes have also been removed from the docs, and replaced with more informative descriptions on the fields.