bpo-40896: add missing links to source-code to library documentation #20843
Conversation
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. | |||
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.
| @@ -6,6 +6,8 @@ | |||
|
|
|||
| .. sectionauthor:: A.M. Kuchling <amk@amk.ca> | |||
|
|
|||
| **Source code:** :source:`Lib/curses/panel.py` | |||
There was a problem hiding this comment.
This one is not really useful.
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 |
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.
| @@ -8,6 +8,8 @@ | |||
| .. 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. | |||
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. |
| @@ -5,6 +5,10 @@ | |||
|
|
|||
| .. sectionauthor:: Benjamin Peterson <benjamin@python.org> | |||
|
|
|||
| **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. |
https://bugs.python.org/issue40896