[Core] Add service_name.json #17159

qwordy · 2021-03-02T03:47:02Z

Description

Add a file service_name.json. It maintains service information of commands.

We propose to add a "reference summaries" section. It groups command by service or topic. It offers a more organized way for users to view commands. This file is the source data of this doc page.
https://docs.microsoft.com/en-us/cli/azure/azure-cli-reference-for-data-share?view=azure-cli-latest

Twin PR, Azure/azure-cli-extensions#3083

Example

  {
    "Command": "az acr",
    "Description": "Manage private registries with Azure Container Registries.",
    "AzureServiceName": "Azure Container Registries",
    "ConversationalServiceName": "Container Registries",
    "URL": "https://docs.microsoft.com/azure/container-registry/"
  },

Testing Guide

History Notes

[Component Name 1] BREAKING CHANGE: az command a: Make some customer-facing breaking change.
[Component Name 2] az command b: Add some customer-facing feature.

This checklist is used to make sure that common guidelines for a pull request are followed.

The PR title and description has followed the guideline in Submitting Pull Requests.
I adhere to the Command Guidelines.
I adhere to the Error Handling Guidelines.

yungezz · 2021-03-02T08:48:04Z

src/azure-cli/service_name.json

+    "URL": "https://docs.microsoft.com/azure/cost-management-billing/manage/create-subscription"
+  },
+  {
+    "Command": "az acr",


this file will be manually maintained in future right?

yungezz · 2021-03-02T08:48:56Z

src/azure-cli/service_name.json

+  {
+    "Command": "az cloud",
+    "Description": "Manage registered Azure clouds.",
+    "AzureServiceName": "Azure cloud services",


this is Not auzre cloud service, but should belongs to CLI core part. Pls work with Delora to fix excel.

As mentioned, I would like to eliminate core and put all core stuff under the Azure CLI "service" heading

All Azure CLI core stuff are named "Azure CLI" in AzureServiceName now

yungezz · 2021-03-02T08:49:20Z

src/azure-cli/service_name.json

+  {
+    "Command": "az account",
+    "Description": "Manage Azure subscription information.",
+    "AzureServiceName": "Azure core",


This is not Azure core, but Azure CLI core, pls help to work with delora to fix the excel

yungezz · 2021-03-02T08:51:06Z

src/azure-cli/service_name.json

+  {
+    "Command": "az rest",
+    "Description": "Invoke a custom request.",
+    "AzureServiceName": "Azure core",


This is Azure CLI core, not Azure core. same as above

yungezz · 2021-03-02T08:51:55Z

hi @fengzhou-msft could you pls review this one? thanks

daxianji007 · 2021-03-04T09:42:35Z

src/azure-cli/service_name.json

+    "Command": "az acs",
+    "Description": "Manage Azure Container Services.",
+    "AzureServiceName": "Azure Container Services",
+    "ConversationalServiceName": "Container Services",


What is the difference between AzureServiceName and ConversationalServiceName? If I want to aggregate all the commands from the same service in the reference documents, which one should be the key?

AzureServiceName has "Azure" while ConversationalServiceName does not based on observation.
@dbradish-microsoft Can you help answer it?

fengzhou-msft · 2021-03-10T03:20:53Z

A question about the json format, should we add a key for each item so the item can be retrieved quickly with the key like:

{
  "az acr": {
    "Command": "az acr",
    "Description": "Manage private registries with Azure Container Registries.",
    "AzureServiceName": "Azure Container Registries",
    "ConversationalServiceName": "Container Registries",
    "URL": "https://docs.microsoft.com/azure/container-registry/"
  }
},

qwordy · 2021-03-10T09:23:22Z

A question about the json format, should we add a key for each item so the item can be retrieved quickly with the key like:

{
  "az acr": {
    "Command": "az acr",
    "Description": "Manage private registries with Azure Container Registries.",
    "AzureServiceName": "Azure Container Registries",
    "ConversationalServiceName": "Container Registries",
    "URL": "https://docs.microsoft.com/azure/container-registry/"
  }
},

It is also a viable structure.

dbradish-microsoft · 2021-03-10T22:00:24Z

src/azure-cli/service_name.json

+    "ExtensionName": "",
+    "URL": "https://docs.microsoft.com/azure/container-registry/"
+  },
+  {


@yungezz , @qwordy , @jiasli , @fengzhou-msft

This is a duplicate comment also found in PR 3083

Important: Shuang is already keeping a new JSON file which replaces TitleMapping.json and where this information would fit perfectly. Ideally, we'd like to avoid having engineering enter autogenerated content in multiple places. Can we please check with Alice Wang and Shuang Jiang on a consolidated place for this information?

Other thoughts:

I feel we should remove "Description" as it is a duplicate of the autogenerated content. There is no reason for making someone enter the same information in two different places, correct?

Isn't "extensionName" also a duplicate from what is found in the _help.py or commands.py files? Shuang is currently showing this information at the top of every autogenerated extension page and he doesn't use this new file.

URL is not necessary unless we want to a.) take responsibility for maintaining this link or b.) use it in our autogenerated content. I had it in SQL in order to find the Azure service home page for my reference (vs Googling it every time I needed it)

I am glad to see "conversational service name" removed -- that was only for my Power BI internal reporting.

(1) The information of service_name.json is part of Azure CLI. We seldom put content in Azure CLI Doc repo. (2) TitleMapping.json is aggregated data. service_name.json is raw data. It is easier to read and maintain. Each entry is a command (group).

Each command has a description. It is a duplicate info.

The extension name is not an explicit value in _help.py or commands.py. It is also used to check which extension does not have an entry.

Since we have already written them, I prefer keeping them. Autogenerated content can provide this link to allow readers to jump to the service page.

Yes. This column causes confusion.

@qwordy, You do realize that TitleMapping.json is going away, correct? I'm honestly not trying to put my nose into the "how" of the Azure DevOps work items for references, but I do feel that I made a tone of new work for engineering that I'd like to minimize so that you all still kind of like me for the next couple of years.

The above link is for the Azure DevOps epic. Here are the related features which all require new reference metadata content. Attached to the features is an example JSON file I created in an effort to communicate the request detail:

Missing extension information -- done
Combine core and extension references on the TOC -- the subject of this PR
Autogen of Azure service reference summaries
Add reference name, command and parameter types, status, version and deprecated message at the parameter level
Catch-all feature for any remaining data-driven metadata not already completed

Shuang's new JSON file for reference metadata is here

@dbradish-microsoft @daxianji007 Are these two files beneficial? My assumption is we maintain service_name.json and .docsreference.azurecli.json is generated. If it is more convenient to keep only one file, it is OK to abandon this PR.

@qwordy @dbradish-microsoft I am afraid the file ".docsreference.azurecli.json" cannot be automatically generated. It has some (and will have more) conceptual content, such as TitleMapping and Service Page Description. From my point of view, one file is certainly more convenient for both maintenance and Docs generation. I can also accept spliting the mapping into two service_name.json in 2 repos (actually the new pipeline is ready for both way). It is up to you.

@daxianji007, I agree with "the file .docsreference.azurecli.json cannot be autogenerated...", but I am not understanding the "two service_name.json in 2 repos" that we just added. The engineering team is going to have to maintain 3 different files with this design, correct? Is there a way to give @yungezz and her team a single data entry file to maintain?

@daxianji007 @dbradish-microsoft
I am OK with both solutions. If one file is more convenient, let's just abandon service_name.json and close these 2 PRs. One last question, who will maintain .docsreference.azurecli.json?

@qwordy, I defer to @yungezz or @rloutlaw to answer your question.

…name

qwordy · 2021-03-24T06:27:21Z

@dbradish-microsoft Can you revoke the "request change"? Thanks.

qwordy · 2021-03-29T07:11:33Z

I moved content to these 2 PRs.
#17428
Azure/azure-cli-extensions#3186

…name

qwordy · 2021-04-01T02:49:10Z

Reopen this PR. The following two new PRs that contain linter and service_name.json are still in review. Reviewing Azure CLI Core code is always hard. As a result, I decide to split linter and service_name.json into separate PRs. Let's merge the service_name.json PR first.
#17428
Azure/azure-cli-extensions#3186

qwordy added 2 commits March 2, 2021 11:22

[Core] Add service_name.json

42b6269

remove en-us

1690344

qwordy mentioned this pull request Mar 2, 2021

[Core] Add service_name.json Azure/azure-cli-extensions#3083

Merged

3 tasks

yonzhan requested a review from jiasli March 2, 2021 04:52

yungezz reviewed Mar 2, 2021

View reviewed changes

yungezz added the Documentation label Mar 2, 2021

yungezz assigned fengzhou-msft Mar 2, 2021

daxianji007 reviewed Mar 4, 2021

View reviewed changes

qwordy requested a review from dbradish-microsoft March 5, 2021 05:28

update

b25d1d8

qwordy requested a review from fengzhou-msft March 9, 2021 06:56

houk-ms approved these changes Mar 9, 2021

View reviewed changes

kairu-ms approved these changes Mar 10, 2021

View reviewed changes

delete a column

004b1df

dbradish-microsoft requested changes Mar 10, 2021

View reviewed changes

yungezz approved these changes Mar 17, 2021

View reviewed changes

Merge branch 'dev' of https://github.com/Azure/azure-cli into service…

e67ae92

…name

dbradish-microsoft approved these changes Mar 24, 2021

View reviewed changes

qwordy closed this Mar 29, 2021

qwordy reopened this Apr 1, 2021

qwordy added 2 commits April 1, 2021 10:35

Merge branch 'dev' of https://github.com/Azure/azure-cli into service…

97cf80e

…name

Update service_name.json

009c0f6

fengzhou-msft approved these changes Apr 1, 2021

View reviewed changes

qwordy merged commit 7b68db9 into Azure:dev Apr 1, 2021

[Core] Add service_name.json #17159

[Core] Add service_name.json #17159

Uh oh!

Conversation

qwordy commented Mar 2, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yungezz commented Mar 2, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fengzhou-msft commented Mar 10, 2021

Uh oh!

qwordy commented Mar 10, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dbradish-microsoft Mar 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qwordy commented Mar 24, 2021

Uh oh!

qwordy commented Mar 29, 2021

Uh oh!

qwordy commented Apr 1, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

qwordy commented Mar 2, 2021 •

edited

Loading

dbradish-microsoft Mar 11, 2021 •

edited

Loading

qwordy commented Apr 1, 2021 •

edited

Loading