parser with `[*]` in any string causes sphinx warning for `Inline emphasis start-string without end-string`

[raven42]

If I use the following example program:

"""
Test script

.. argparse::
    :module: test
    :func: test_parser
    :prog: test.py
"""

import argparse

def test_parser():
    parser = argparse.ArgumentParser(description='Test script with [*] in description',
                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
    parser.add_argument('--arg1', help='Argument with [*] in help')
    parser.add_argument('--arg2', help='Another argument with bracketed asterisk in metavar', metavar='[*.blah]')
    return parser

def main():
    parser = test_parser()
    args = parser.parse_args()

    print(args)

if __name__ == '__main__':
    main()

It produces the following Inline emphasis warning when compiling the sphinx docs.

...
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.
None:1: (WARNING/2) Inline emphasis start-string without end-string.

Build finished. The HTML pages are in _build/html.

Open in web-browser (chrome/chromium-browser preferred):
    file:///home/user/project/doc/_build/html/index.html

It compiles fine and views fine in the output file, but the warnings are being flagged in the pre-commit hooks for my project.

It seems specific to including a bracket with an asterisk in it. I believe the sphinx-argparse parser might need to sanitize the help / description statements before writing out the html. I'm assuming this would also be the case for the epilog as well.

I'm using python 3.8.5 with sphinx 4.0.2 and sphinx-argparse 0.3.1.

[RobertoRoos]

Still relevant in Python 3.10, Sphinx 7.3.7 and sphinx-argparse 0.3.1.

I'll look into making a pull request with a potential fix.

In the meantime, you can work around using the @after flag, to replace a specific argument with proper ReST code. For example, I have the following argument in Python:

        parser.formatter_class = ArgumentDefaultsHelpFormatter
        # ....
        parser.add_argument(
            "--filter",
            help="Target files only with these patterns",
            nargs="+",
            default=["*.tsproj", "*.xti", "*.plcproj"],
        )

Which causes a warning because the asterisks are used for formatting.
But not when I overwrite the specific argument in the ReStructuredText code:

.. argparse::
   :module: my.module
   :func: get_parser

   --filter : @replace
      Target files only with these patterns

      Default: ['\*.tsproj', '\*.xti', '\*.plcproj']

[RobertoRoos]

Actually @ashb , I'm not sure this is entirely fixed: special characters in the help parameter are untouched still.

But that will also require a bit of consideration, because we want to allow some Sphinx syntax.