classification
Title: Sphinx incompatible markup in the standard library
Type: Stage: patch review
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Patrick Lehmann, docs@python, georg.brandl, lukasz.langa, r.david.murray, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2016-11-16 00:59 by Patrick Lehmann, last changed 2016-12-28 23:19 by lukasz.langa.

Files
File name Uploaded Description Edit
docstring_markup.patch Patrick Lehmann, 2016-11-16 23:23 markup changes in docstrings
Messages (10)
msg280907 - (view) Author: Patrick Lehmann (Patrick Lehmann) * Date: 2016-11-16 00:59
Why does e.g. configparser.ConfigParser contain doc strings with Sphinx incompatible markup?

The markup starts with back-tick, but ends with a single quote.

Example:
https://github.com/python/cpython/blob/master/Lib/configparser.py?ts=2#L26

Sphinx writes these messages:
D:\git\PoC\py\lib\ExtendedConfigParser\__init__.py:docstring of lib.ExtendedConfigParser.ExtendedConfigParser.read_file:3: WARNING: Inline interpreted text or phrase reference start-str
ing without end-string.

Note: ExtendedConfigParser is class derived from configparser.ConfigParser. Inherited methods get documented too.

------------------------
Btw. I have some improvements for this class, how can I contribute them? Who is the maintainer for this class? Please contact me: Patrick.Lehmann@tu-dresden.de

The improved version is available at GitHub: https://github.com/Paebbels/ExtendedConfigParser?ts=2
msg281005 - (view) Author: Patrick Lehmann (Patrick Lehmann) * Date: 2016-11-16 22:50
How can I supply a fix?

I have a branch with lots of fixes.
https://github.com/Paebbels/cpython/tree/paebbels/issue-28710?ts=2

Why don't you accept pull requests via GitHub?


Kind regards
    Patrick
msg281007 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-11-16 23:00
We will accept github pull requests in the future (the transition is underway).

For now, you can create a diff file (using hg diff by preference, but git diff will work) and uploaded it to the issue.  For this issue, please only upload the docstring changes.  For other enhancement suggestions, open separate issues.  (This would be true even if we were accepting pull requests).

The existing docstring markup is probably a remnant of the days when the documentation was written in LaTeX.

Lukasz Langa is the current maintainer of this module.
msg281010 - (view) Author: Patrick Lehmann (Patrick Lehmann) * Date: 2016-11-16 23:23
Here is the patch file created with:
PS> git diff > docstring_markup.patch

This patchfile effects all files with this markup in the CPython repository.


Kind regards
    Patrick
msg281162 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-11-18 20:16
As far as I looked, the patch changes `xyz' in docstrings and quotes to ``xyz``.  A rst expert should verify that this is correct.  In printed strings, `zyz' is changed to 'xyz', which I consider to be correct.

Before applying this, I would want to review in Rietveld, with side by side diff and changes color marked.  However, Rietveld does not like the patch and there is no 'review' button.  I thought it might be the git format, but I found another git patch that did have a review button.  When I downloaded and tried to apply (to default), hg says that there is no diff.  I don't see the problem, but we cannot currently use a patch that does not apply in hg.

Patrick, in order to use patches, we require Contributor Agreements.
https://www.python.org/psf/contrib/
There is an electronic form that makes submission easy.
https://www.python.org/psf/contrib/contrib-form/
msg281165 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-11-18 20:36
I think that we do not generally use ReST markup in our docstrings.  So replacing `x' with 'x' would be more correct, I think.  In many cases the quotes could just be omitted entirely.

The patch command says:

  patch unexpectedly ends in middle of line
  patch: **** Only garbage was found in the patch input.
msg281197 - (view) Author: Patrick Lehmann (Patrick Lehmann) * Date: 2016-11-19 03:30
Hello,

I used this regexp on all files:
--------------------------------------
match pattern: `([A-Za-z0-9_]+)'
replace pattern ``\1``
--------------------------------------
I assumed that only identifiers where quoted in such way. I think my editor found around 139 matches in the whole CPython repository.

I found some of these markup in non docstring strings, which I reverted as far as I found them by manually reviewing all changed files.

For a colored diff, see my Git branch: https://github.com/Paebbels/cpython/commit/6d3f348f71b5b0ae9fbfcb8fdbba72dc5fac428a?ts=2
There is also a PR-, commit-, and line-based comment feature box GitHub.

How you solve it is up to you, but I would like to get rid of hundreds of warnings in my Sphinx runs, when modules are inherting code (and docstrings) from Python.

Kind regards
    Patrick
msg281198 - (view) Author: Patrick Lehmann (Patrick Lehmann) * Date: 2016-11-19 03:39
.... I signed the CLA.
msg281261 - (view) Author: Patrick Lehmann (Patrick Lehmann) * Date: 2016-11-20 11:10
I also found some docstrings using double back-tick plus double single quotes.

For example: ``x.y = v'' in builtins.py in function setattr(...).
msg284206 - (view) Author: Ɓukasz Langa (lukasz.langa) * (Python committer) Date: 2016-12-28 23:19
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.
History
Date User Action Args
2016-12-28 23:19:12lukasz.langasetmessages: + msg284206
title: Sphinx incompatible markup in configparser.ConfigParser. -> Sphinx incompatible markup in the standard library
2016-11-20 12:24:18serhiy.storchakasetnosy: + georg.brandl
2016-11-20 11:10:24Patrick Lehmannsetmessages: + msg281261
2016-11-19 03:39:44Patrick Lehmannsetmessages: + msg281198
2016-11-19 03:30:48Patrick Lehmannsetmessages: + msg281197
2016-11-18 20:36:58r.david.murraysetmessages: + msg281165
2016-11-18 20:16:48terry.reedysetnosy: + terry.reedy

messages: + msg281162
stage: needs patch -> patch review
2016-11-16 23:23:34Patrick Lehmannsetfiles: + docstring_markup.patch
keywords: + patch
messages: + msg281010
2016-11-16 23:00:50r.david.murraysetnosy: + r.david.murray, lukasz.langa
messages: + msg281007
2016-11-16 22:50:02Patrick Lehmannsetmessages: + msg281005
2016-11-16 06:53:54serhiy.storchakasetkeywords: + easy
stage: needs patch
versions: + Python 2.7, Python 3.6, Python 3.7, - Python 3.4
2016-11-16 00:59:42Patrick Lehmanncreate