[docs] [issue22558] Missing doc links to source code for Python-coded modules.
report at bugs.python.org
Fri Jun 3 18:08:43 EDT 2016
Nathan Harold added the comment:
I went through all the diffs in Rietveld, checking it against msg228576 as I went. There were (naturally) more source links added than there are in that list from 2014, and there were also many more files with slight header reorganizations for consistency. Anything in the diffs I don't mention here looked fine to me. I also built the docs to test links in general and to see how some specific things here looked.
A number of the new links are to __init__.py files, and others are to folders rather than individual source files. I noticed a precedent for the former in the case of the http module; for the latter I'm less certain, but I can see that it makes sense in some cases, e.g. when __init__.py is empty. I think these are probably good.
One thing I particularly noticed was that in imp.rst and optparse.rst, the deprecation notice occurred below the source link, whereas the versionadded notices are always above it. I think it would be more consistent and look more natural to have the deprecation notices above the source links.
This could be taken a step farther by suggesting that the source link always be the last visible thing before the horizontal line. The two other cases this would affect here are asyncio.rst (the notice that the module is provisional is between the source link and line) and getopt.rst (the note, now moved above the line, is after the source link). But this is all fairly subjective.
Other details for individual files:
marshal.rst - Here an index block a bit farther down into the text was moved up into the header. I think these might have been intended to point right where they were, not to the module as a whole; those things occur only in the paragraph (or two, in the case of 'code object') immediately following where the index originally pointed.
unittest.mock-examples.rst - A versionadded notice was completely removed from this file. In fact, that was the only change to this file. I think I can see why you did this, since the actual API documentation for the library is in unittest.mock.rst, which has that same version notice.
array.rst - -------------- was inserted above .. index:
fcntl.rst - Patch appears to apply correctly, but with fuzz.
os.path.rst - It might be good to put a space in "WindowsNT"
termios.rst - Patch fails to apply because some other text near the header has changed recently.
venv.rst - The source code link (to a folder) works, but is missing a trailing slash.
Terry, I got the same results when I tried applying it to 3.5, so I think a single patch will do.
Python tracker <report at bugs.python.org>
More information about the docs