Quotes in auto-documented class attributes should be straight quotes in PDF output

[jfbu]

With the following

class Foo:
    """Docstring for 'my' class Foo."""

    #: Doc "comment" for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = "1"

    flox = "1.5"   #: Doc "comment" for Foo.flox. One line only.

    baz = "2"
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for "instance" attribute qux.
        self.qux = "3"

        self.spam = "4"
        """Docstring for 'instance' attribute spam."""

in module foocode.py and

.. automodule:: foocode
   :members:

one gets curly quotes for the Python str's with Sphinx 1.5.6 in PDF output:

This looks wrong.

Now at Sphinx stable (ab2cc9d, 1.6.3+) it is different, but again wrong: only closing curly quotes are used for '1' for example.

Problem

The mechanism at 1.5.6 was that foo='1' gave `1' in tex file. Indeed the text, not being a literal, was submitted to the educate_quotes_latex. This happened independently of the html_use_ smartypants config setting. The problem in Latex indeed is that text fonts automatically apply a replacement mechanism and the ' in latex file becomes a closing English curly quote in PDF. And one must in TeX input match the closing ' with an opening `. Of course this means PDF will be OK only if English curly quotes are OK.

At 1.6.1, PR #3666 was merged. Now, Docutils smartquotes transform is applied. This applies to all builders. So in the context above '1' would get converted into using the suitable opening and closing quotes for language in use (if available).

Now, at current stable head, (but not at 1.6.2) (*) the SmartQuotes is inhibited inside object description signatures. Thus the latex file will contain '1' as in the reST source.

(*) there is something weird at 1.6.2 for language set to French (for example) that English double curly quotes are used, although in normal text it will correctlybe the French ones. I do not at this time understand this, but anyhow at stable head, SmartQuotes is inhibited there.
edit: this was an effet of #3880 issue. It still shows in docstrings as explained at #3880.

As explained above this '1' in tex source becomes ’1’ in PDF.

Thus to fix there are only three ways:

• use \sphinxcode or \sphinxbfcode. This is actually what the Latex macros \py@sigparams or \production (inside productionlist environment`) do.

• apply some escaping via latex writer to use \textsinglequote in place of '. But now we have delegated escaping to Docutils smart quotes which is for all builders.

• make temporarily ' an "active" TeX character which will use \textsinglequote (this is actually mechanism at work inside \sphinxcode, already implemented and complex).

The simplest would be to modify the definitions in LaTeX writer such as

    def visit_desc_annotation(self, node):
        # type: (nodes.Node) -> None
        self.body.append(r'\sphinxstrong{')

to use rather \sphinxbfcode. Currently the tex file contains for example

\pysigline{\sphinxbfcode{bar}\sphinxstrong{ = `1'}}

Replacing \sphinxstrong by \sphinxbfcode would fix the problem but it would change the font to be the mono font.

Sorry for very long description of problem. This is to serve for future maintenance of never ending problems with quotes!

Environment info

• OS: Mac
• Python version: 3.5.3
• Sphinx version: 1.5.6, 1.6.1, 1.6.2, current stable head (ab2cc9d)

Relates

#3666
#3875