botbuilder-python icon indicating copy to clipboard operation
botbuilder-python copied to clipboard

Remove colon (':') from keywords such as "Parameters" and "Remarks" in comments

Open kexugit opened this issue 2 years ago • 0 comments

Github issues should be used for bugs and feature requests. Use Stack Overflow for general "how-to" questions.

Version

Latest

Describe the bug

Keywords such as "Parameters" and "Remarks" used in comments, if followed by colon (':'), will generate unwanted H1 headers in API reference documents.

See the proper usage in: https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html

To Reproduce

  1. Source code: https://github.com/microsoft/botbuilder-python/blob/a7ae841a87dc4edbeb110a2486a220fb33667c02/libraries/botbuilder-ai/botbuilder/ai/qna/utils/train_utils.py#L20
  2. API reference document generated based on the source code: https://review.learn.microsoft.com/en-us/python/api/botbuilder-ai/botbuilder.ai.qna.utils.train_utils.trainutils?branch=sphinx6.1.3-compare&view=botbuilder-py-latest#botbuilder-ai-qna-utils-train-utils-trainutils-call-train

Expected behavior

Remove colon (':') after the keywords (Parameters, Remarks, Returns) in the comments so that they can be rendered properly in API reference documents

Screenshots

If applicable, add screenshots to help explain your problem.

Additional context

https://dev.azure.com/ceapex/Engineering/_workitems/edit/793397

kexugit avatar Mar 27 '23 22:03 kexugit