classification
Title: Provide a link from documentation back to its source file
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Mariatta Nosy List: Mariatta, brett.cannon, docs@python, terry.reedy
Priority: normal Keywords: patch

Created on 2016-12-10 00:58 by brett.cannon, last changed 2017-03-31 16:36 by dstufft. This issue is now closed.

Files
File name Uploaded Description Edit
issue28929dev.patch Mariatta, 2016-12-11 04:47 patch for versions >= 3.5 review
issue28929-v27.patch Mariatta, 2016-12-12 02:58 patch for 2.7 review
Pull Requests
URL Status Linked Edit
PR 35 Mariatta, 2017-02-12 03:59
PR 36 Mariatta, 2017-02-12 04:00
PR 37 Mariatta, 2017-02-12 04:00
PR 38 Mariatta, 2017-02-12 04:06
PR 112 merged Mariatta, 2017-02-15 05:09
PR 284 merged Mariatta, 2017-02-25 03:38
PR 285 merged Mariatta, 2017-02-25 03:42
PR 286 merged Mariatta, 2017-02-25 03:46
PR 703 larry, 2017-03-17 21:00
PR 552 closed dstufft, 2017-03-31 16:36
Messages (18)
msg282818 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-12-10 00:58
It would be great if we provided a link from a documentation page back to the source file that the page is produced from, e.g. have https://docs.python.org/3.6/library/abc.html provide a link to https://github.com/python/cpython/blob/3.6/Doc/library/abc.rst.
msg282830 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-12-10 06:10
On the left menu, there's already a Show Source link. 
Is the idea to replace that link to github.com/python/cpython/blob/.... ?

Or, are you thinking about adding a new link under the main heading, similar to 
**Source code:** :source:`Lib/abc.py` 
but for the docs, so maybe by creating a new role like:
**Docs Source code:** :docs_source:`Doc/library/abc.rst`
msg282866 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-12-10 19:45
Either idea works, but I want a link that someone who finds a spelling mistake can easily follow and submit a PR to fix the issue.
msg282867 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-12-10 19:50
Thanks, Brett :) I think it's easier to update the existing Source Link to github. I'll work on a patch for this.
msg282902 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-12-11 04:47
Hi,
This patch updates the Show Source link on the left of Docs menu and point it to github.
I tested it locally, and works for versions >= 3.5 
Please let me know if you have any feedback about this.
Thanks :)

Not sure if the older docs versions should be updated too? In that case, I'll need to prepare different patches for 3.4, 3.3 and 2.7
msg282937 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2016-12-11 19:01
Thanks for the patch, Mariatta! Once we have migrated to GitHub we can apply the patch (don't let me forget :) ).

Any version still under active maintenance should probably be updated, so that would probably mean 2.7 but not the other versions.
msg282959 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-12-12 02:58
Thanks, Brett.

Here's the patch that will work for the 2.7 branch.
msg283450 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-12-16 23:35
Nice idea.  I agree with an updated sidebar link, both aesthetically and as a practical matter for doc maintainers.
msg287592 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-02-11 05:00
Now that we have migrated to GitHub and Mariatta is a core dev I'm assigning this to her. :)
msg287651 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-02-12 21:19
Thanks all :)
PRs have been merged on GitHub.
Closing this.
msg290396 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-24 23:43
New changeset 23d2c31cbf3032b8c6bb254f06c4532a6db466b6 by Mariatta in branch '2.7':
[2.7] bpo-28929: Add to Misc/NEWS (GH-286)
https://github.com/python/cpython/commit/23d2c31cbf3032b8c6bb254f06c4532a6db466b6
msg290397 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-24 23:43
New changeset 5023686f7ee69e9da07cda4b7da6691f19892111 by Mariatta in branch '3.5':
[3.5] bpo-28929: Add to Misc/NEWS (GH-285)
https://github.com/python/cpython/commit/5023686f7ee69e9da07cda4b7da6691f19892111
msg290398 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-24 23:43
New changeset 1a8dd944d4016593e78a7a6c3c635adee783abfd by Mariatta in branch '3.6':
[3.6] bpo-28929: Add to Misc/NEWS (GH-284)
https://github.com/python/cpython/commit/1a8dd944d4016593e78a7a6c3c635adee783abfd
msg290405 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-24 23:47
New changeset e3bf4cdd3db9004220d3ec7f5db4e7d16a99c743 by Mariatta in branch 'master':
bpo-28929: Add to Misc/NEWS (GH-112)
https://github.com/python/cpython/commit/e3bf4cdd3db9004220d3ec7f5db4e7d16a99c743
msg290441 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-25 00:22
New changeset f66c81ff499fb431e56bc68f5e39c2f7b9fcb6a7 by Mariatta in branch '3.6':
[backport to 3.6] bpo-28929: Link the documentation to its source file on GitHub (#37)
https://github.com/python/cpython/commit/f66c81ff499fb431e56bc68f5e39c2f7b9fcb6a7
msg290442 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-25 00:23
New changeset d4a97d894859d4bb52937d46460049ba016e00b2 by Mariatta in branch 'master':
bpo-28929: Link the documentation to its source file on GitHub (#35)
https://github.com/python/cpython/commit/d4a97d894859d4bb52937d46460049ba016e00b2
msg290443 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-25 00:23
New changeset e15259c2dfef58df5f7cfa2305811a00c05e0353 by Mariatta in branch '2.7':
bpo-28929: Link the documentation to its source file on GitHub (#38)
https://github.com/python/cpython/commit/e15259c2dfef58df5f7cfa2305811a00c05e0353
msg290444 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-03-25 00:24
New changeset cabd1c7462ef991937e0e759b9bf307b3091ef06 by Mariatta in branch '3.5':
[backport to 3.5] bpo-28929: Link the documentation to its source file on GitHub (#36)
https://github.com/python/cpython/commit/cabd1c7462ef991937e0e759b9bf307b3091ef06
History
Date User Action Args
2017-03-31 16:36:29dstufftsetpull_requests: + pull_request1023
2017-03-25 00:24:59Mariattasetmessages: + msg290444
2017-03-25 00:23:29Mariattasetmessages: + msg290443
2017-03-25 00:23:03Mariattasetmessages: + msg290442
2017-03-25 00:22:34Mariattasetmessages: + msg290441
2017-03-24 23:47:13Mariattasetmessages: + msg290405
2017-03-24 23:43:48Mariattasetmessages: + msg290398
2017-03-24 23:43:39Mariattasetmessages: + msg290397
2017-03-24 23:43:29Mariattasetmessages: + msg290396
2017-03-17 21:00:34larrysetpull_requests: + pull_request600
2017-02-25 03:46:16Mariattasetpull_requests: + pull_request256
2017-02-25 03:42:27Mariattasetpull_requests: + pull_request255
2017-02-25 03:38:45Mariattasetpull_requests: + pull_request254
2017-02-15 05:09:13Mariattasetpull_requests: + pull_request75
2017-02-12 21:19:51Mariattasetstatus: open -> closed
resolution: fixed
messages: + msg287651

stage: needs patch -> resolved
2017-02-12 04:06:08Mariattasetpull_requests: + pull_request38
2017-02-12 04:00:20Mariattasetpull_requests: + pull_request37
2017-02-12 04:00:05Mariattasetpull_requests: + pull_request36
2017-02-12 03:59:49Mariattasetpull_requests: + pull_request35
2017-02-12 03:48:06Mariattasetversions: + Python 2.7, Python 3.5, Python 3.6, Python 3.7
2017-02-11 05:00:12brett.cannonsetassignee: docs@python -> Mariatta
messages: + msg287592
2016-12-16 23:35:29terry.reedysetnosy: + terry.reedy
messages: + msg283450
2016-12-12 02:58:11Mariattasetfiles: + issue28929-v27.patch

messages: + msg282959
2016-12-11 19:01:25brett.cannonsetmessages: + msg282937
2016-12-11 04:47:04Mariattasetfiles: + issue28929dev.patch
keywords: + patch
messages: + msg282902
2016-12-10 19:50:12Mariattasetmessages: + msg282867
2016-12-10 19:45:37brett.cannonsetmessages: + msg282866
2016-12-10 06:10:52Mariattasetnosy: + Mariatta
messages: + msg282830
2016-12-10 00:58:56brett.cannoncreate