python-sphinxsmart-quotes

How to ensure correct Smart Quotes in Sphinx?


I am trying to generate some HTML from restructured text using Sphinx. If my source code contains things between straight single quotes, Sphinx will give me aligned quotes nearly always, but with some exceptions. For example, if the input is 'X' I get ‘X’ as expected, but if it is '-', I see ‘-‘.

Is there way to get Sphinx to do this properly, i.e. ‘-’ ?

I have tried escaping the quotes and/or the hyphen but no success.

Using Sphinx 2.2.1, Debian 10.


Contents of index.rst

Smart Quotes
============

* 'X'
* '_'
* '-'
* 'K'.

Contents of conf.py

# -- Project information -----------------------------------------------------

project = 'Smart Quotes'
copyright = '2019, '
author = 'P'

# The full version, including alpha/beta/rc tags
release = '1'

Build command:

sphinx-build . _build/html

What it will look like:

enter image description here

Note that the second quotation mark on the dash looks different from the other examples.


Solution

  • I suggest filing an issue report in Sphinx. This looks like a bug to me, although it could be a bug in the underlying docutils library's utility smartquotes.

    That said, there is a workaround. Use the following reStructuredText sample below.

    Smart Quotes On
    ===============
    
    * '-'
    * ‘-’
    * "-"
    * “-”
    

    If you must keep smartquotes enabled, then you can use literal smart quotes to get the correct typographical interpretation.

    Smart Quotes On

    I prefer to disable smartquotes in my conf.py with smartquotes = False and use the literal typographic characters when I want them.

    enter image description here

    Finally, although you could use an em-dash, en-dash, or other dash character instead of a hyphen to have what appears to be visually correct to the untrained eye, that would replacing one a typographical blunder for another.