search

Azure / azure-cli

Azure Command-Line Interface
MIT License
3.97k stars 2.95k forks source link

Where are the YAML Schema Files? #18440

Closed ezwiefel closed 3 years ago

ezwiefel commented 3 years ago

For each of the az ml CLI commands that accept a YAML file, the documentation should include the link to the schema file to make authoring easier and should also show an example to make it clear.

This should be done directly in the CLI documentation and not through other areas (such as docs.microsoft.com examples)

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

lostmygithubaccount commented 3 years ago

for now, you can view the JSON schemas which are at the top of most examples - we are working on proper YAML schema documentation similar to github actions workflows: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

ghost commented 3 years ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @azureml-github.

Issue Details
For each of the `az ml` CLI commands that accept a YAML file, the documentation should include the link to the schema file to make authoring easier and should also show an example to make it clear. This should be done directly in the CLI documentation and not through other areas (such as docs.microsoft.com examples) --- #### Document Details ⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.* * ID: 110fd5df-299e-f288-867f-c307a2f2ba9f * Version Independent ID: ac8d15ce-b17b-8da8-8d60-cf98d448c9bd * Content: [az ml model](https://docs.microsoft.com/en-us/cli/azure/ml/model?view=azure-cli-latest) * Content Source: [latest/docs-ref-autogen/ml/model.yml](https://github.com/MicrosoftDocs/azure-docs-cli/blob/master/latest/docs-ref-autogen/ml/model.yml) * GitHub Login: @rloutlaw * Microsoft Alias: **routlaw**
Author: ezwiefel
Assignees: -
Labels: `Machine Learning`, `Service Attention`, `needs-triage`
Milestone: -
yonzhan commented 3 years ago

route to service team

ezwiefel commented 3 years ago

@lostmygithubaccount - The YAML schema documentation would be great. In the meantime, even the JSON schemas would be fine... if it were linked to the CLI documentation.

My overarching feedback is that when a YAML file is consumed by the CLI, the CLI documentation (e.g. https://docs.microsoft.com/en-us/cli/azure/ml/model?view=azure-cli-latest) should have a link to the schema.

Our technical documentation (CLI, SDK, REST, etc.) should be self-sufficient and shouldn't require users to search for examples to figure out how to leverage.

lostmygithubaccount commented 3 years ago

there will be multiple YAML schemas per CLI command, e.g. az ml job would have CommandJob, SweepJob, and potentially more schemas.

az ml endpoint has a schema for Online, Batch, and separately for deployments.

Certainly agree that technical documentation should be self-sufficient, we are actively working to improve reference documentation and will make this a priority.

ghost commented 3 years ago

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @lostmygithubaccount.

Issue Details
For each of the `az ml` CLI commands that accept a YAML file, the documentation should include the link to the schema file to make authoring easier and should also show an example to make it clear. This should be done directly in the CLI documentation and not through other areas (such as docs.microsoft.com examples) --- #### Document Details ⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.* * ID: 110fd5df-299e-f288-867f-c307a2f2ba9f * Version Independent ID: ac8d15ce-b17b-8da8-8d60-cf98d448c9bd * Content: [az ml model](https://docs.microsoft.com/en-us/cli/azure/ml/model?view=azure-cli-latest) * Content Source: [latest/docs-ref-autogen/ml/model.yml](https://github.com/MicrosoftDocs/azure-docs-cli/blob/master/latest/docs-ref-autogen/ml/model.yml) * GitHub Login: @rloutlaw * Microsoft Alias: **routlaw**
Author: ezwiefel
Assignees: -
Labels: `ADO`, `ML-MLOps`, `Machine Learning`, `Service Attention`, `customer-reported`
Milestone: -
paulshealy1 commented 3 years ago

Closing this issue. We'll continue to work on improving the documentation.