-
-
Notifications
You must be signed in to change notification settings - Fork 30.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
bpo-40896: add missing links to source-code to library documentation #20843
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Documentation only changes don't need a blurb.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This one is not really useful.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@remilapeyre Why, Has it been deprecated?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also deprecated.
@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