bpo-40896: add missing links to source-code to library documentation #20843
Conversation
remilapeyre
left a comment
remilapeyre
left a comment
There was a problem hiding this comment.
Thanks @SimiCode, except curses.panel.rst that contains no code I think you got them all.
| @@ -0,0 +1 @@ | |||
| Add links to Library source code to Documentation. Enhanced by Edison Abahurire. No newline at end of file | |||
There was a problem hiding this comment.
Documentation only changes don't need a blurb.
There was a problem hiding this comment.
But they can and for non-trivial changes ofter do. 'Documentation' is a section in the blurb template and in the changelog.
https://docs.python.org/3/whatsnew/changelog.html#changelog
I would change and expand to
"Add source links to doc for 2to3, asyncio/, ..., curses/, ... wsgiref."
There was a problem hiding this comment.
I think in this case it could be reasonable either way, but I wouldn't consider it to be strictly required for small documentation enhancements.
|
|
||
| .. sectionauthor:: A.M. Kuchling <[email protected]> | ||
|
|
||
| **Source code:** :source:`Lib/curses/panel.py` |
There was a problem hiding this comment.
@remilapeyre Why, Has it been deprecated?
There was a problem hiding this comment.
Not, it's just that the file is a wrapper for the C module: https://github.com/python/cpython/blob/master/Lib/curses/panel.py
There was a problem hiding this comment.
Thanks for the PR @SimiCode.
In the case of the asyncio documentation changes, some of the source code links were intentionally omitted as not being particularly relevant or additionally useful for the reader's understanding. Also, in the case of the link to the source code for asyncio, it's already displayed in the footer of the documentation and doesn't need to be displayed at the top as well.
For more details, see Yury's review comments on my PR that was merged last year: #16640.
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
terryjreedy
left a comment
terryjreedy
left a comment
There was a problem hiding this comment.
We started with a few, then some more, and then some more. I am sure some of these were intentionally left out, but the line is fuzzy and the added space in the doc small. Where the package has a maintainer, you might ask if there is a really good reason for the omission.
| .. deprecated:: 3.4 | ||
| Due to lack of usage, the formatter module has been deprecated. | ||
|
|
||
| **Source code:** :source:`Lib/formatter.py` |
There was a problem hiding this comment.
I an not sure that adding this for a deprecated module is a good idea.
| @@ -0,0 +1 @@ | |||
| Add links to Library source code to Documentation. Enhanced by Edison Abahurire. No newline at end of file | |||
There was a problem hiding this comment.
But they can and for non-trivial changes ofter do. 'Documentation' is a section in the blurb template and in the changelog.
https://docs.python.org/3/whatsnew/changelog.html#changelog
I would change and expand to
"Add source links to doc for 2to3, asyncio/, ..., curses/, ... wsgiref."
|
Hi @SimiCode, thanks for your work! Please address the last comments of the code review. |
|
|
||
| .. sectionauthor:: Benjamin Peterson <[email protected]> | ||
|
|
||
| **Source code:** :source:`Lib/lib2to3` |
|
@edison12a Would you still be interested in addressing some of the comments above? I can clone and create a new PR if not. |
|
If you'd like to resume the PR let me know and I can reopen. In the meanwhile, see #99363 instead. |
9 participants
https://bugs.python.org/issue40896