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

This is a configuration option in Sphinx that is on by default: the html_use_smartypants option (http://sphinx-doc.org/config.html?highlight=dash#confval-html_use_smartypants).

If you turn off the option, then you will have to use the Unicode character '–' if you want an en-dash.

Answer 2

With

**-\\-region**  <region_name>

it should work.

Answer 3

To add two dashes, add the following:

.. include:: <isotech.txt>

|minus|\ |minus|\ region

Note the backward-slash and the space. This avoids having a space between the minus signs and the name of the parameter.

You only need to include isotech.txt once per page.

With this solution, you can keep the extension smartypants and write two dashes in every part of the text you need. Not just in option lists or literals.

Answer 4

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.