Would like feedback from @ImportanceOfBeingErnest before merge.

Seems reasonable to me - smartquotes are horrible.

There is a slight chance I'm missing some implication of this proposed change, but as far as I can currently see, there is indeed no need for smart-quotes in the docs.

What I did find are just harmless cases like below (look at the word "styles"; top is without smart-quotes, bottom with smart-quotes):

In such cases, it doesn't really hurt to have them turned on - some people may find it more appealing actually.

Now it might help to turn smart-quotes off, because without smartquotes you may easily copy and paste text from the docs to the editor without the need to convert back to normal quotes - but I'm not sure if there are cases where that would apply in the matplotlib docs.

@timhoffm Is there any place in the docs where this change is particularly apparent or which motivated you to propose to turn them off, such that people can get a visual impression of the impact of this PR?

Possible implications to check:

• Does this affect how the latex docs are produced/rendered in an undesireable way?
• Are there cases where a double - (--) is used to create hyphens (–) which would then read as --? (This shouldnt be blocker, but one might then want to correct those.)

In LaTeX I'd normally do

``boo''

to get proper quotes. If that works for sphinx, then I'm 👍 on this change. If not, then neutral.

The motivation is stated in the original post:

Since we mainly use quotes to represent python strings in the docs without additional formatting (``'text'`` is really too cumbersome and visually distracting in plain docstrings), using straight quotes instead of typographic quotes is the better choice.

Some examples:

smart:

plain:

smart:

plain:

smart:

plain:

@ImportanceOfBeingErnest We indeed have a number of double-dashes (--). That would need fixing. Or better, is there a way to apply smartquotes to the dashes but not to the quotes. The docutils don't really say something about this. One could inject this by defining regular quotes in smartquotes_locales for English, but that's a bit hacky.

Very much agree that smartquotes have no business in anything that is rendered as code... thats terrible...

My tendancy is to merge this and fix any problems we find, but I won't merge right away in case others want a say....

Indeed, one can keep the dashes and just deactivate the quotes. 🎉

Now I see the point. Ideally, code should be code and hence embraced by double backticks (``).
However instead of doing this everywhere you would like to make this one change that fixes all of those cases.

Just mind that in that case you cannot keep the dashes (hyphens), because e.g. the linestyle "--" would still become a hyphen, as in

That's not nice. The idea was in the context of #10225 (section String Values), which is a pattern widely used in the docs.

For the above case of an accepts-list one could quite easily convert strings to literal strings while building the docs. However, I don't think it's easy to patch this into sphinx/numpydoc for rendering the original type infos.

Maybe we nevertheless have to go for the long cumbersome string literals ``'text'``? Alternatives would be deactivating smart quotes completely or escaping the --. The latter may however be confusing when looking at the plain text docs.

Do we really use -- that often for a hyphen? Personally I think just disable that as well; having a couple space "--" in the rendered docs is not as bad as having a long hyphen when we mean two dashes.

Yes, there are a lot of --: grep -R ' -- ' | wc yields 89 results.

Perhaps just add an escape (backslash) when we don't want the conversion? Yes, that makes the source a bit less legible at that point but it's a tradeoff to consider...

The escape would be really weird in the definitions of the line styles.

What I would prefer output-wise is a plain string in the plain docs but literal formatting in the html output. Can we intercept sphinx when processing parameter types and replace 'word' by ``'word'``?

going back to the simple

smartquotes = False

For future reference. The alternative solution would be:

smartquotes = True
smartquotes_action = 'De'  # only replace 'D'ashes and 'e'llipses, not quotes

This is currently not chosen as it would convert the double dash in linestyle='--' into an em dash.

I think that makes sense... If someone wants to get worked up about -- in the main text, they can go through and fix....

Merging - the test failures were yesterday's kerfuffle...