使Sphinx在PDF输出中生成未混淆的代码块

Question

Code blocks look ugly (check the quotes) in PDF output:

I use version 1.1.3 of Sphinx, and used the following command to produce the doc:

$ make latexpdf

Also, copying the snippet from the PDF destroys the indenting when pasting:

@view_config(route_name=’hello’)
def hello_world(request):
return Response(’Hello World!’)

I would expect this:

@view_config(route_name=’hello’)
def hello_world(request):
    return Response(’Hello World!’)

This would be even nicer:

@view_config(route_name='hello')
def hello_world(request):
    return Response('Hello World!')

Answer 1

Sphinx is really an excellent tool but I also have a few issues with the default PDF output of the latexpdf target.

Specifically:

• Single quotes in code blocks are converted to acute style quotes which doesn't look right in source code.
• The code blocks aren't indented from the main text. For me this makes them less readable.
• I prefer other fonts and pygments but that is just a personal choice and can be configured.

Some of this can be fixed in the LaTeX pre-amble section of the Sphinx conf.py but the quotes are modified by Sphinx to custom LaTeX entities so the upquote LaTeX package can't be used to correct them.

After a good bit of experimentation with different config options I ended up writing a small script to modify the LaTeX source prior to building the PDF. The script is here and the output that I wanted to generate is here . (For comparison here is the default output for the same document.)

If someone has a cleaner solution, for example one that could be done completely through Sphinx conf.py so the changes would be picked up by ReadTheDocs then I would be interested.

Also, the issue with losing indentation when copying and pasting from the PDF probably isn't a Sphinx/LaTeX issue.

Answer 2

This is only a partial answer which may lead toward an ultimate solution. To disable typographer quotes (also known as curly or smart quotes) for HTML output in Sphinx, change the default setting in conf.py for SmartyPants from True to False .

I assume that one could find the function in Sphinx that transforms quotes and use the same logic from the HTML output and apply it for PDF output.

Answer 3

The option proposed by Steve Piercy now no longer works (since Sphinx 1.6):

Deprecated since version 1.6: Use the smart_quotes option 
in the Docutils configuration file (docutils.conf) instead.

What was not obvious to me was how to apply this setting. You need to create a docutils.conf file and put it in one of these locations :

• /etc/docutils.conf
• ./docutils.conf
• ~/.docutils

The easiest option is to put it where you are building the docs from - YMMV. It should contain at least this:

[general]
smart_quotes: no