How to handle two dashes in ReST

Question

I'm using Sphinx to document a command line utility written in Python. I want to be able to document a command line option, such as --region like this:

**--region**  <region_name>

in ReST and then use Sphinx to to generate my HTML and man pages for me.

This works great when generating man pages but in the generated HTML, the -- gets turned into - which is incorrect. I have found that if I change my source ReST document to look like this:

**---region**  <region_name>

The HTML generates correctly but now my man pages have --- instead of --. Also incorrect.

I've tried escaping the dashes with a backslash character (e.g. \-\-) but that had no effect.

Any help would be much appreciated.

Answer 1

In Sphinx 1.6 html_use_smartypants has been deprecated, and it is no longer necessary to set html_use_smartypants = False in your conf.py or as an argument to sphinx-build. Instead you should use smart_quotes = False.

If you want to use the transformations formerly provided by html_use_smartypants, instead it is recommended to use smart_quotes, e.g., smart_quotes = True.

Note that at the time of this writing Read the Docs pins sphinx==1.5.3, which does not support the smart_quotes option. Until then, you'll need to continue using html_use_smartypants.

EDIT It appears that Sphinx now uses smartquotes instead of docutils smart_quotes. h/t @bad_coder.