pydoc removes 'self' in HTML for method docstrings with example code

[CameronHayne]

BPO	13223
Nosy	@ezio-melotti, @merwok, @skrah, @berkerpeksag
Files	issue13223.python3k.patch: Patch for the in-development (main) branch issue13223.python2.7.patch: Patch for the 2.7 branch pydoc-self.patch issue13223_tests.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-06-07.23:47:26.312>
created_at = <Date 2011-10-19.18:59:41.803>
labels = ['easy', 'type-bug', 'library']
title = "pydoc removes 'self' in HTML for method docstrings with example code"
updated_at = <Date 2014-06-21.09:08:16.981>
user = 'https://bugs.python.org/CameronHayne'

bugs.python.org fields:

activity = <Date 2014-06-21.09:08:16.981>
actor = 'neologix'
assignee = 'none'
closed = True
closed_date = <Date 2014-06-07.23:47:26.312>
closer = 'python-dev'
components = ['Library (Lib)']
creation = <Date 2011-10-19.18:59:41.803>
creator = 'Cameron.Hayne'
dependencies = []
files = ['23801', '23802', '35525', '35695']
hgrepos = []
issue_num = 13223
keywords = ['patch', 'easy']
message_count = 10.0
messages = ['145937', '145996', '148540', '148559', '175916', '219978', '220002', '220848', '221034', '221162']
nosy_count = 9.0
nosy_names = ['ezio.melotti', 'eric.araujo', 'skrah', 'neologix', 'python-dev', 'berker.peksag', 'vterron', 'Cameron.Hayne', 'shiinee']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue13223'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[CameronHayne]

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.

[vterron]

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.

[vterron]

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 bpo-13223: Fix pydoc.writedoc so that the HTML documentation for methods that use 'self' in the example code is generated correctly."

[merwok]

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.)

[ezio-melotti]

Víctor, can you address my comment on rietveld?

[shiinee]

The patch still applies cleanly, so I've just updated the comment. test passes, make patchcheck passes.

[python-dev]

New changeset 7aa72075d440 by Benjamin Peterson in branch '3.4':
don't remove self from example code in the HTML output (closes bpo-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 bpo-13223)
http://hg.python.org/cpython/rev/e89c39125892

New changeset cddb17c4975e by Benjamin Peterson in branch 'default':
merge 3.4 (bpo-13223)
http://hg.python.org/cpython/rev/cddb17c4975e

[skrah]

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

[berkerpeksag]

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.

[neologix]

Berker, I've committed your patch, thanks!