With Sphinx's default smartquotes = True, any --option mentioned in a help string, description, or epilog renders as –option (en dash), so the documented text no longer matches what the command line accepts. The generated option names are unaffected (they are literals) - only mentions inside help text.
You can see this bug in the wild in quite a lot of places, here's one - https://kafka-python.readthedocs.io/en/master/cli/consumer.html: The file owns handlers/formatters, so –log-format, –log-date-format and –log-file are ignored, but –enable-logger and –disable-logger still apply as logger level adjustments.. I discovered this in one of my own projects, but am currently working around it like this: https://github.com/mmulqueen/pyStrich/blob/3c5a6767d1fb3a5b0b1da602fd644baf89d56e72/docs/conf.py#L351
This was previously reported as alex-rudakov/sphinx-argparse#73 (2017) and closed with only the global smartquotes = False workaround, which sacrifices typography across the whole project.
I have a patch and will submit a PR shortly.
With Sphinx's default smartquotes = True, any --option mentioned in a help string, description, or epilog renders as –option (en dash), so the documented text no longer matches what the command line accepts. The generated option names are unaffected (they are literals) - only mentions inside help text.
You can see this bug in the wild in quite a lot of places, here's one - https://kafka-python.readthedocs.io/en/master/cli/consumer.html:
The file owns handlers/formatters, so –log-format, –log-date-format and –log-file are ignored, but –enable-logger and –disable-logger still apply as logger level adjustments.. I discovered this in one of my own projects, but am currently working around it like this: https://github.com/mmulqueen/pyStrich/blob/3c5a6767d1fb3a5b0b1da602fd644baf89d56e72/docs/conf.py#L351This was previously reported as alex-rudakov/sphinx-argparse#73 (2017) and closed with only the global
smartquotes = Falseworkaround, which sacrifices typography across the whole project.I have a patch and will submit a PR shortly.