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.

I have found that one simple solution to this is to wrap the double-hyphens inside code markup, e.g. \`\`--region\`\` rather than \*\*--region\*\*. There may be more elegant ways to solve it but that works for me. — garnaat, Mar 07 '13 at 13:51
Maybe you can use an option list: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists — mzjn, Mar 07 '13 at 17:19
Yeah, that seems kind of appropriate. Thanks, still discovering new things in ReST all the time! — garnaat, Mar 07 '13 at 20:49

score 4 · Answer 1 · answered Mar 12 '13 at 05:44

4

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.

answered Mar 12 '13 at 05:44

Joseph

539
5
13

This is of course a workaround. I consider this behaviour as bug though because it cannot be so hard to just first replace '--' with endash and after '---' with emdash. – TNT Feb 05 '14 at 11:40
1

And in the sense of this feature for example ``:command:`sphinx-build --version` `` yields a "typographically correct" command line: `sphinx-build —–version`... – TNT Feb 05 '14 at 12:03

Steve Piercy · Answer 2 · 2021-03-19T06:26:52.800

2

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.

edited Mar 19 '21 at 06:26

answered Aug 15 '17 at 08:32

Steve Piercy

13,693
1
44
57

1

Notice to readers, syntax has changed to [`smartquotes = False`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes). It was this one-liner configuration that solved the double-dash `--` problem for me. – bad_coder Mar 18 '21 at 23:56

score 2 · Answer 3 · answered Aug 30 '17 at 15:53

2

With

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

it should work.

answered Aug 30 '17 at 15:53

score 0 · Answer 4 · answered Mar 28 '17 at 20:16

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.

score 0 · Answer 5 · answered Jun 20 '20 at 05:11

As commented by @mzjn, the best way to address the original submitter's need is to use Option Lists.

The format is simple: a sequence of lines that start with -, --, + or /, followed by the actual option, (at least) two spaces and then the option's description:

-l     long listing
-r     reversed sorting
-t     sort by time
--all  do not ignore entries starting with .

The number of spaces between option and description may vary by line, it just needs to be at least two, which allows for a clear presentation (as above) on the source, as well as on the generated document.

Option Lists have syntax for an option argument as well (just put an additional word or several words enclosed in <> before the two spaces); see the linked page for details.

The other answers on this page targeted the original submitter's question, this one addresses their actual need.

How to handle two dashes in ReST

5 Answers5

Linked