Fix option name for smart quotes in sphinxdoc conf

[atugushev]

Fixes transform double dashes to a long dash. For the instance you can see this issue in this section.

Correct option name described here: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes

---

Before

---

After

[cjerdonek]

Thanks, @atugushev! Can you add a doc news entry since this is a user-visible change / improvement? https://pip.pypa.io/en/stable/development/contributing/#news-entries

[atugushev]

@cjerdonek done!

[cjerdonek]

On second thought, how would you feel about using backticks instead (code formatting) for such options appearing inline in the text? It seems like "smart quoting" leads to better formatting for true text, and that way we could avoid having to sacrifice good formatting for one over good formatting for the other. Also, on the page you linked to, I noticed a number of spots that aren't using backticks when it should, e.g.

by default is “<venv path>/src/SomeProject”

or are using backticks incorrectly, e.g.

(if not disabled via `--no-index`)

[cjerdonek]

Also, in cases where using backticks might not work correctly (e.g. nested situations like inside :ref:), can you do something like slash-escape the dashes to disable the smart-quoting?

[atugushev]

slash-escape the dashes to disable the smart-quoting

I've tried slash-escape, but it doesn't work as expected.

It seems like "smart quoting" leads to better formatting for true text, and that way we could avoid having to sacrifice good formatting for one over good formatting for the other.

Agree. Maybe it's better to turn smartquotes on and configure this plugin to not trasform dashes by option smartquotes_action = "qe" (exclude D). See details for smartquotes_action.

[atugushev]

@cjerdonek now it looks better! Thanks for fixing the news entry text!

[cjerdonek]

Yes, I think it's an improvement! But there's still the issue that options appearing inside Sphinx "roles" like :ref: are getting formatted differently because it doesn't permit nested backticks. E.g. (though the second one is without your change)

And also textual dashes won't get converted as a result.

What about not putting option flags inside roles, and instead doing something like putting the hyperlink afterwards in a footnote or parentheses?

[cjerdonek]

@atugushev I fixed up some of the wording, etc. and included more explanation of why smartquotes_action is being set. If it looks good to you, I'll merge.

[atugushev]

LGTM 👍

[cjerdonek]

Thanks again for this improvement! 😄

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.