[issue28710] Sphinx incompatible markup in the standard library docstrings

Terry J. Reedy added the comment: I agree with David. I would like the ugly markup changed independent of how Sphinx treats it. I was thinking of changing the title to "Change obsolete tex markup in stdlib docstrings". The intent of `word' was for people to see balanced quotes, which in a

[issue28710] Sphinx incompatible markup in the standard library docstrings

R. David Murray added the comment: I would still like to see the legacy tex markup removed from the docstrings, so I think closing this issue is not appropriate, but it's not a big enough deal that I'll push for it if Raymond wants to keep it closed. -- _

[issue28710] Sphinx incompatible markup in the standard library docstrings

Raymond Hettinger added the comment: Marking this as closed. Though well-intentioned, the suggestion is predicated on a misperception of the role of Sphinx for CPython and existing PEP recommendations on docstring practices. -- nosy: +rhettinger resolution: -> not a bug stage: patc

[issue28710] Sphinx incompatible markup in the standard library docstrings

Terry J. Reedy added the comment: RestructuredText, DocUtils, and Sphinx were developed independently, by people other than the pydev/cpython group. (The proposal to include DocUtils in the stdlib was rejected.) We converted to .rst for the Python documentation sources files about a decade

[issue28710] Sphinx incompatible markup in the standard library docstrings

Patrick Lehmann added the comment: Having single quotes in docstrings is also ok for Sphinx documentation. Btw. ReStructured text (docutils) was invented to document Python sources, why is it not used by Python? -- ___ Python tracker

[issue28710] Sphinx incompatible markup in the standard library docstrings

Serhiy Storchaka added the comment: Oh, you are right. I didn't write much English TeX, and used other types of quotes. I'm sure that I seen `such quotation' in non-TeX files, but maybe my memory fools me. In any case using this writing here is likely an artifact of copying from a TeX docum

[issue28710] Sphinx incompatible markup in the standard library docstrings

Terry J. Reedy added the comment: > AFAIK `name' is common writing of quotes in English texts I don't remember ever seeing it before. It looks like a typo to me, and I am sure it will to most readers. I think it should be corrected as if it were a typo. -- ___

[issue28710] Sphinx incompatible markup in the standard library docstrings

R. David Murray added the comment: No, it is (somewhat) unique to tex. If you write `word' tex would turn that into a pair of opposing quotes in the typeset document, as opposed to 'word' (the convention in regular text/emails/posts/etc) where you'd just see ascii quotes. tex would render

[issue28710] Sphinx incompatible markup in the standard library docstrings

Serhiy Storchaka added the comment: What is the problem? Docstrings are not written in the reStructuredText format in general. If Sphinx complains about docstrings in the stlib, don't run Sphinx for the stdlib files or report a Sphinx bug. Even if remove all `x', docstrings still will not be

[issue28710] Sphinx incompatible markup in the standard library docstrings

R. David Murray added the comment: By the way, in case anyone is curious, I'm pretty sure that markup is left over from the days when tex/latex was what docs were *written* in. -- ___ Python tracker ___

[issue28710] Sphinx incompatible markup in the standard library docstrings

R. David Murray added the comment: Right, my opinion is that we shouldn't be putting markup in docstrings. They are (from our point of view) pure text. I don't know if discussion on python-dev is warranted, it seems like a fairly uncontroversial change, since it brings the docstrings in que

[issue28710] Sphinx incompatible markup in the standard library docstrings

Change by Raymond Hettinger : -- title: Sphinx incompatible markup in the standard library -> Sphinx incompatible markup in the standard library docstrings ___ Python tracker

[issue28710] Sphinx incompatible markup in the standard library

Terry J. Reedy added the comment: In my last comment above, I forgot that this issue is about *docstrings*. We do not officially process docstrings with Sphinx, so there are no warnings to be suppressed. PEP 8, which covers style for the stdlib, refers to https://www.python.org/dev/peps/pe

[issue28710] Sphinx incompatible markup in the standard library

Raymond Hettinger added the comment: This should probably be discussed on python-dev. In particular, changing from single backticks to double backticks is something that makes Sphinx happy but will uglify the docstrings for all other ways of viewing the docs. Also, note that most of our doc

[issue28710] Sphinx incompatible markup in the standard library

Terry J. Reedy added the comment: master, and maybe backport from there, unless the PR never touches master. I wonder if we should bring this up on pydev. Without discussion and agreement, someone might object just because there are so many changes. Or someone might say that they want the

[issue28710] Sphinx incompatible markup in the standard library

Patrick Lehmann added the comment: Against what branch should I create the PR? I was a huge number of changes. I think I'll create multiple PRs to ease the review. -- ___ Python tracker

[issue28710] Sphinx incompatible markup in the standard library

Terry J. Reedy added the comment: I agree with David about replacing `x' with 'x' instead of ``x``, so please make this change. Do you know what ``x.y = v'' is supposed to mean? David, do you want one PR with 139+ changes, or should we start with fewer? Patrick, are these usages scattered

[issue28710] Sphinx incompatible markup in the standard library

R. David Murray added the comment: Thanks for coming back to this. We're accepting PRs via github now, so the next step now would be to make it into a PR. Sometimes things just get forgotten and you have to nudge them to get them moving (see the devguide for guidelines about when it is ap

[issue28710] Sphinx incompatible markup in the standard library

Patrick Lehmann added the comment: Any progress on that issue? 1.5 years passed by and it should be possible to fix the Python documentation in that time, right? -- ___ Python tracker _

[issue28710] Sphinx incompatible markup in the standard library

Łukasz Langa added the comment: Marking as a stdlib-wide issue since it's not configparser-specific. FYI, as you probably noticed, the `term' syntax predates Sphinx and is used in lots of places. While I think it would be nice to fix it, it's a big diff. -- title: Sphinx incompatible m