classification
Title: pydoc removes 'self' in HTML for method docstrings with example code
Type: behavior Stage: resolved
Components: Library (Lib) Versions: Python 3.5, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: Cameron.Hayne, berker.peksag, eric.araujo, ezio.melotti, neologix, python-dev, shiinee, skrah, vterron
Priority: normal Keywords: easy, patch

Created on 2011-10-19 18:59 by Cameron.Hayne, last changed 2014-06-21 09:08 by neologix. This issue is now closed.

Files
File name Uploaded Description Edit
issue13223.python3k.patch vterron, 2011-11-29 03:23 Patch for the in-development (main) branch review
issue13223.python2.7.patch vterron, 2011-11-29 05:02 Patch for the 2.7 branch review
pydoc-self.patch shiinee, 2014-06-07 21:23 review
issue13223_tests.diff berker.peksag, 2014-06-19 21:56 review
Messages (10)
msg145937 - (view) Author: Cameron Hayne (Cameron.Hayne) Date: 2011-10-19 18:59
If the docstring for a method has example code that uses 'self',
the 'self' will not appear in the HTML generated by pydoc.writedoc

Example:
#---------------------------------
def getAnswer(self):
    """
    Return the answer.
    Example of use:
        answer = self.getAnswer()
    """
    return 42
#---------------------------------

The generated HTML will have:

getAnswer(self)
    Return the answer.
    Example of use:
        answer = getAnswer()

where the final "getAnswer" is an HTML link.
--------------------------------------------

I believe the problem arises on line 553 of the Python 2.7 version of pydoc.py which is as follows:
    results.append(self.namelink(name, methods, funcs, classes))
The appended text is the same whether or not the method call in the docstring was prefaced with 'self' or not. The 'self' has been eaten up by the regex and is in the 'selfdot' variable which is ignored by the above line.
msg145996 - (view) Author: Víctor Terrón (vterron) * Date: 2011-10-20 01:09
FWIU, only the name of the method, getAnswer, would be a HTML link in the "self.getAnswer()" line that pydoc should generate, while strong (highlighted) text would be used for instance attributes.

I have written a patch for that, by checking for "self." matches (and differentiating between methods and instance attributes) *before* trying to match functions or class instantiations.

It seems to work, but I will test it thoroughly tomorrow.
msg148540 - (view) Author: Víctor Terrón (vterron) * Date: 2011-11-29 03:23
Patch updated with the test cases. I have added a third class to Lib/test/pydoc_mod.py and updated two of the existing cases, test_text_doc and test_html_doc, accordingly.

The news entry could be: "Issue #13223: Fix pydoc.writedoc so that the HTML documentation for methods that use 'self' in the example code is generated correctly."
msg148559 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-29 13:09
Patch looks good to me.  Ezio, do you have time to review too?

(I had forgotten that there were tests checking the exact HTML output.  This won’t be fun when we overhaul pydoc to make it generate sensible HTML.)
msg175916 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-18 20:15
Víctor, can you address my comment on rietveld?
msg219978 - (view) Author: Skyler Leigh Amador (shiinee) Date: 2014-06-07 21:23
The patch still applies cleanly, so I've just updated the comment. test passes, make patchcheck passes.
msg220002 - (view) Author: Roundup Robot (python-dev) Date: 2014-06-07 23:47
New changeset 7aa72075d440 by Benjamin Peterson in branch '3.4':
don't remove self from example code in the HTML output (closes #13223)
http://hg.python.org/cpython/rev/7aa72075d440

New changeset e89c39125892 by Benjamin Peterson in branch '2.7':
don't remove self from example code in the HTML output (closes #13223)
http://hg.python.org/cpython/rev/e89c39125892

New changeset cddb17c4975e by Benjamin Peterson in branch 'default':
merge 3.4 (#13223)
http://hg.python.org/cpython/rev/cddb17c4975e
msg220848 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2014-06-17 18:14
I guess the tests --without-doc-strings are broken:

http://buildbot.python.org/all/builders/AMD64%20FreeBSD%209.0%203.x/builds/6900/steps/test/logs/stdio
msg221034 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-06-19 21:56
> I guess the tests --without-doc-strings are broken:
> http://buildbot.python.org/all/builders/AMD64%20FreeBSD%209.0%203.x/builds/6900/steps/test/logs/stdio

Attached patch fixes these failures.
msg221162 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2014-06-21 09:08
Berker, I've committed your patch, thanks!
History
Date User Action Args
2014-06-21 09:08:16neologixsetnosy: + neologix
messages: + msg221162
2014-06-19 21:56:14berker.peksagsetfiles: + issue13223_tests.diff
versions: + Python 3.5, - Python 3.2, Python 3.3
nosy: + berker.peksag

messages: + msg221034
2014-06-17 18:14:13skrahsetnosy: + skrah
messages: + msg220848
2014-06-07 23:47:26python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg220002

resolution: fixed
stage: patch review -> resolved
2014-06-07 21:23:41shiineesetfiles: + pydoc-self.patch
nosy: + shiinee
messages: + msg219978

2012-11-18 20:15:13ezio.melottisetmessages: + msg175916
versions: + Python 3.4
2011-11-29 13:09:58eric.araujosetversions: + Python 3.2, Python 3.3
nosy: + eric.araujo

messages: + msg148559

stage: test needed -> patch review
2011-11-29 05:02:21vterronsetfiles: + issue13223.python2.7.patch
2011-11-29 03:23:37vterronsetfiles: + issue13223.python3k.patch

messages: + msg148540
2011-11-29 03:20:18vterronsetfiles: - issue13223.patch
2011-10-20 01:09:43vterronsetfiles: + issue13223.patch

nosy: + vterron
messages: + msg145996

keywords: + patch
2011-10-19 21:49:44ezio.melottisetkeywords: + easy
nosy: + ezio.melotti

stage: test needed
2011-10-19 18:59:41Cameron.Haynecreate