Sphinx, ReadTheDocs and Dashes

For my documentation, I often have to document *nix command-line stuff. No problem until you have to document options that come along with commands.

In Sphinx you have the ":command:" directive to show commands in a uniform way. However, if the command has options that are indicated with a double-dash, the double-dash is by default converted to a single dash.

For example: ":command:`./mycommand.py --myoptions options.ini`" would render as "./mycommand.py -myoptions option.ini". Very annoying indeed, since people tend to copy/paste commands and then they are surprised that "it doesn't work".

Weird thing is that in my local Sphinx setup, using 1.3a0, the rendering is correct, but in the default Sphinx version 1.2.x (if I'm not mistaken, also used by ReadTheDocs), I have the single dash. After looking around on the web, found that the parameter "html_use_smartypants" in the Sphinx conf.py file is the culprit. This parameter is by default disabled, but the smartypants is not disabled by Sphinx and ReadTheDocs itself. This smartypants converts the double dash to a single dash or sometimes en-dash (or em-dash). Since the parameter was commented I didn't take notice of it, but I didn't come to the proper rendering.

To actually disable the smartypants, you have to literally set it to False and then I finally have the correct rendering of my double dash.

# If true, SmartyPants will be used to convert quotes and dashes to

# typographically correct entities.

html_use_smartypants = False

/me happy to start the last day of the week.