{Docs} Quote code in help messages with backticks by jiasli · Pull Request #13060 · Azure/azure-cli

jiasli · 2020-04-17T03:56:20Z

Description
Fix #10698: az ad app permission add description not understandable

Symptom

The doc for az ad app permission add is not rendered correctly, with the value of --api-permissions missing.

https://docs.microsoft.com/en-us/cli/azure/ad/app/permission

Root Cause

The reason is that the doc generator parses <resource-access-id> and <type> as a possible HTML entities:

azure-cli/src/azure-cli/azure/cli/command_modules/role/_params.py

Line 61 in 1f34245

    
           c.argument('api_permissions', nargs='+', help='space seperated list of <resource-access-id>=<type>')

but they don't match up with any entities on the Docs HTML Whitelist, and the content is discarded.

This happens not only to this command but all over the place, including VM, Network and more commands.

Solution

This PR quotes the text with backticks ` like what azure-cli-core does for --resource-group:

azure-cli/src/azure-cli-core/azure/cli/core/commands/parameters.py

Line 241 in c4e91c0

    
           help="Name of resource group. You can configure the default group using `az configure --defaults group=<name>`",

In this way, the doc is rendered correctly (even better with highlighting due to backtick (`) being interpreted as code in markdown), such as

https://docs.microsoft.com/en-us/cli/azure/acs

⚠ But the disadvantage is the --help message may look verbose.

Remarks

I searched the occurrence of <> with regex <.+?> (? stands for non-greedy match) and added backticks manually.

jiasli · 2020-04-17T03:56:52Z

src/azure-cli/azure/cli/command_modules/keyvault/_params.py

        c.argument('network_acls', type=validate_file_or_dict,
                   help='Network ACLs. It accepts a JSON filename or a JSON string. JSON format: '
-                        '{\\"ip\\":[<ip1>, <ip2>...],\\"vnet\\":[<vnet_name_1>/<subnet_name_1>,<subnet_id2>...]}')
+                        '`{\\"ip\\":[<ip1>, <ip2>...],\\"vnet\\":[<vnet_name_1>/<subnet_name_1>,<subnet_id2>...]}`')


@bim-msft

https://docs.microsoft.com/en-us/cli/azure/keyvault

Thanks for pointing it out.

jiasli · 2020-04-17T03:57:14Z

src/azure-cli/azure/cli/command_modules/resource/_params.py

    with self.argument_context('managedapp definition create') as c:
        c.argument('lock_level', arg_type=get_enum_type(ApplicationLockLevel), help='The type of lock restriction.')
-        c.argument('authorizations', options_list=['--authorizations', '-a'], nargs='+', help="space-separated authorization pairs in a format of <principalId>:<roleDefinitionId>")
+        c.argument('authorizations', options_list=['--authorizations', '-a'], nargs='+', help="space-separated authorization pairs in a format of `<principalId>:<roleDefinitionId>`")


@Juliehzl @zhoxing-ms

https://docs.microsoft.com/en-us/cli/azure/managedapp/definition

jiasli · 2020-04-17T03:57:35Z

src/azure-cli/azure/cli/command_modules/network/_params.py

    with self.argument_context('network public-ip prefix') as c:
        c.argument('public_ip_prefix_name', name_arg_type, completer=get_resource_name_completion_list('Microsoft.Network/publicIPPrefixes'), id_part='name', help='The name of the public IP prefix.')
-        c.argument('prefix_length', options_list='--length', help='Length of the prefix (i.e. XX.XX.XX.XX/<Length>)')
+        c.argument('prefix_length', options_list='--length', help='Length of the prefix (i.e. `XX.XX.XX.XX/<Length>`)')


@myronfanqiu

https://docs.microsoft.com/en-us/cli/azure/network/public-ip/prefix

jiasli · 2020-04-17T03:57:36Z

src/azure-cli/azure/cli/command_modules/vm/_params.py

    with self.argument_context('vmss create', min_api='2017-03-30', arg_group='Network') as c:
        c.argument('public_ip_per_vm', action='store_true', help="Each VM instance will have a public ip. For security, you can use '--nsg' to apply appropriate rules")
-        c.argument('vm_domain_name', help="domain name of VM instances, once configured, the FQDN is 'vm<vm-index>.<vm-domain-name>.<..rest..>'")
+        c.argument('vm_domain_name', help="domain name of VM instances, once configured, the FQDN is `vm<vm-index>.<vm-domain-name>.<..rest..>`")


@qwordy

https://docs.microsoft.com/en-us/cli/azure/vmss

How do you send picture?

How do you send picture?

Create a screenshot and paste it into input box? I guess.
This is the way I used.

qwordy · 2020-04-17T08:18:59Z

How do you preview the rendered html page to see the result is expected?
How do you open a draft PR?

jiasli · 2020-04-22T03:17:35Z

How do you preview the rendered html page to see the result is expected?

I don't know how to "preview the rendered html page". I am deducing it from the global params --resource-group and --location. +@daxianji007 to clarify.

How do you open a draft PR?

See this blog and this help:

qwordy · 2020-04-22T03:18:57Z

I encounter a same issue of a new parameter I add in Azure CLI 2.4.0. Only at release time can I see the HTML page. This is the problem!

yonzhan · 2020-04-22T03:33:45Z

add to S169

zhoxing-ms

LGTM

fengzhou-msft

Can we put a guidance in authoring_help.md?

jiasli · 2020-04-30T06:09:38Z

doc/authoring_help.md

 - Don't use "etc". Sometimes it makes sense to spell out a list completely. Sometimes it works to say "like ..." instead of "..., etc".
 - Use active voice. For example, say "Update web app configurations" instead of "Updates web app congfigurations" or "Updating web app configurations".
 - Don't use highly formal language. If you imagine that another dev sat down with you and you were telling him what he needs to know to use the command, that's exactly what you need to write, in those words.
+- If the help message contains **angle brackets**, like `<name>`, it will be parsed as an HTML tag during document rendering. To bypass that, quote the content with backticks `` `<name>` `` to tell the document renderer to parse it as **code**. 


Can we put a guidance in authoring_help.md?

Good point, added.

jiasli · 2020-04-30T06:15:41Z

doc/authoring_help.md



-### Example YAML help file, _help.py ###
+### Example YAML help file, _help.py


_ breaks GitHub's highlighting.

Suggested change

### Example YAML help file, _help.py

### Example YAML help file, \_help.py

Quote with backticks

a125c03

jiasli requested review from mmyyrroonn and qwordy April 17, 2020 03:56

jiasli commented Apr 17, 2020

View reviewed changes

jiasli requested review from Juliehzl, bim-msft and zhoxing-ms April 17, 2020 03:58

bim-msft approved these changes Apr 17, 2020

View reviewed changes

qwordy approved these changes Apr 22, 2020

View reviewed changes

yonzhan assigned jiasli Apr 22, 2020

yonzhan added this to the S169 - For Build milestone Apr 22, 2020

jiasli mentioned this pull request Apr 22, 2020

{Compute} Update doc of image-version #13112

Merged

2 tasks

jiasli marked this pull request as ready for review April 24, 2020 10:15

jiasli requested review from arrownj, bgklein, fengzhou-msft, haroldrandom and qianwens as code owners April 24, 2020 10:15

zhoxing-ms approved these changes Apr 26, 2020

View reviewed changes

fengzhou-msft approved these changes Apr 30, 2020

View reviewed changes

arrownj approved these changes Apr 30, 2020

View reviewed changes

haroldrandom approved these changes Apr 30, 2020

View reviewed changes

Update doc/authoring_help.md

ac62d23

jiasli commented Apr 30, 2020

View reviewed changes

jiasli requested a review from fengzhou-msft April 30, 2020 06:10

Fix header format

797f880

jiasli commented Apr 30, 2020

View reviewed changes

jiasli added 3 commits April 30, 2020 14:17

Update doc/authoring_help.md

783d961

Escape underscore

a8e1f6b

Fix typo

c90ba46

fengzhou-msft approved these changes Apr 30, 2020

View reviewed changes

bgklein approved these changes Apr 30, 2020

View reviewed changes

jiasli merged commit 2325d7c into Azure:dev May 6, 2020

jiasli mentioned this pull request Jul 9, 2020

{Core} refine local context message #14227

Merged

2 tasks

jiasli deleted the backtick-quote branch July 9, 2020 02:13



		### Example YAML help file, _help.py ###
		### Example YAML help file, _help.py

	### Example YAML help file, _help.py
	### Example YAML help file, \_help.py

Conversation

jiasli commented Apr 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Symptom

Root Cause

Solution

Remarks

Uh oh!

jiasli Apr 17, 2020 • 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!

bim-msft Apr 17, 2020

Choose a reason for hiding this comment

Uh oh!

jiasli Apr 17, 2020 • 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!

jiasli Apr 17, 2020 • 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!

jiasli Apr 17, 2020 • 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!

qwordy Apr 17, 2020

Choose a reason for hiding this comment

Uh oh!

bim-msft Apr 17, 2020

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

jiasli commented Apr 22, 2020

Uh oh!

qwordy commented Apr 22, 2020

Uh oh!

yonzhan commented Apr 22, 2020

Uh oh!

zhoxing-ms left a comment

Choose a reason for hiding this comment

Uh oh!

fengzhou-msft left a comment

Choose a reason for hiding this comment

Uh oh!

jiasli Apr 30, 2020

Choose a reason for hiding this comment

Uh oh!

jiasli Apr 30, 2020

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

jiasli commented Apr 17, 2020 •

edited

Loading

jiasli Apr 17, 2020 •

edited

Loading

jiasli Apr 17, 2020 •

edited

Loading

jiasli Apr 17, 2020 •

edited

Loading

jiasli Apr 17, 2020 •

edited

Loading

qwordy commented Apr 17, 2020 •

edited

Loading