Azure-cli: Documentation: wildcard character * interpreted by markdown

[nbering]

I noticed this on the azure storage blob upload command for the --if-none-match option. * is a special character in markdown and should be escaped, or matched pairs will become a marker for an italicized block.

I'd have updated the markdown file, but I suspect this page was generated, and I would need the escape character added upstream to prevent it from being clobbered.

[tjprescott]

@adewaleo this likely needs to be done as part of the sphinx generation process.

[nbering]

It's been a while since I originally posted this. When the issue finally received a comment, I went back to check if it's still an issue. It is, and can be seen here:

https://docs.microsoft.com/en-us/cli/azure/storage/blob?view=azure-cli-latest#az-storage-blob-upload

[tjprescott]

Thanks @nbering for confirming it is still an issue and providing the link.

[adewaleo]

Being tracked by Docs team here.

[adewaleo]

closing as this is being address by the docs team cc: @daxianji007

[nbering]

Is this closed because it was supposed to be fixed, or just no longer tracked here? I can't see the linked issue, and the public documentation page still has this issue.

[adewaleo]

@nbering I closed this because it is being tracked internally by our docs team. I believe the issue is on their end, as they interpret some help text as markdown, which causes this issue.

cc: @daxianji007 @dend. Please can you follow up on this? Is there a way to track this publicly on your end?

[nbering]

Just curious, really. But also that little feedback that when I volunteer my time to report issues, it's nice to be able to see when it gets closed.

[adewaleo]

@nbering no p. Thanks for following up about this and opening the issue in the first place.

I assumed that given this issue would be handled by the docs team it would be okay to close it. But given your interest in the issue and that the link I posted above is not publicly viewable. I will reopen this issue.

Hopefully @daxianji007 or @dend will be able to close this duplicate of their internally tracked issue when it is resolved.

[daxianji007]

Actually this can be 2 kinds of issues:

1. It is the reStructuredText syntax that turns * to <emphasis>, which is the built-in syntax of sphinx and there is no way to turn it off.
   I have created same issue here
   This is not easy to fix. Currently I just add a post step in Docs CI to turn <emphasis> back to * as work-around.
2. The docs template markup the * to <em>. I am working on it.

[adewaleo]

Actually this can be 2 kinds of issues:

1. It is the reStructuredText syntax that turns * to <emphasis>, which is the built-in syntax of sphinx and there is no way to turn it off.
   I have created same issue here
   This is not easy to fix. Currently I just add a post step in Docs CI to turn <emphasis> back to * as work-around.
2. The docs template markup the * to <em>. I am working on it.

@daxianji007, I hear you. Is there a way we can escape the asterisk to to make this easier for you? We might be able to add some logic in our doc generation scripts / command to escape asterisks or force users to denote asterisks a certain way when authoring help text.

[daxianji007]

@adewaleo @Juliehzl Escaping is easy. Just use \* instead of *. If that can be in the doc generation scripts / command, that would be a perfect solution.

[Juliehzl]

@nbering We are still following up this issue with docs team. @daxianji007 will help us do some change from docs system. @daxianji007 If there is any update, please let me know.

[daxianji007]

fixed. @Juliehzl you can verify it in internal site before next go-live

[adewaleo]

@adewaleo @Juliehzl Escaping is easy. Just use \* instead of *. If that can be in the doc generation scripts / command, that would be a perfect solution.

@daxianji007 @Juliehzl this makes sense from a markdown perspective. However, CLI help (az --help) interprets help content literally, it doesn't interpret it as markdown as CLI's typically emit output in plain text.

This means if * is replaced with \* then the actual help output when --help is run then the user sees \*, unless we add special CLI logic to strip the backslash when the emitting help output.

[daxianji007]

@adewaleo Yes, that is the key point. Now I have added a step in Docs CI to escape the * after sphinx generates xml. This issue should have been resolved. But we need next Docs release to show the fix in Docs page.

[adewaleo]

@daxianji007 I see, thanks for this. What PR was this?

[Juliehzl]

@nbering It is fixed now. Thanks for your feedback. And @daxianji007 thanks a lot for quick action. Also thanks @adewaleo for keeping track of this issue.

[nbering]

Confirmed fixed. Good word!