Provide a link from documentation back to its source file

[brettcannon]

BPO	28929
Nosy	@brettcannon, @terryjreedy, @Mariatta
PRs	bpo-28929: Link the documentation to its source file on GitHub #35 [backport to 3.5] bpo-28929: Link the documentation to its source file on GitHub #36 [backport to 3.6] bpo-28929: Link the documentation to its source file on GitHub #37 [backport to 2.7] bpo-28929: Link the documentation to its source file on GitHub #38 bpo-28929: Add to Misc/NEWS #112 [3.6] bpo-28929: Add to Misc/NEWS #284 [3.5] bpo-28929: Add to Misc/NEWS #285 [2.7] bpo-28929: Add to Misc/NEWS #286 [Do Not Merge] Sample of CPython life with blurb. #703 [Do Not Merge] Convert Misc/NEWS so that it is managed by towncrier #552
Files	issue28929dev.patch: patch for versions >= 3.5 issue28929-v27.patch: patch for 2.7

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/Mariatta'
closed_at = <Date 2017-02-12.21:19:51.697>
created_at = <Date 2016-12-10.00:58:56.838>
labels = ['type-feature', '3.7', 'docs']
title = 'Provide a link from documentation back to its source file'
updated_at = <Date 2017-03-31.16:36:29.320>
user = 'https://github.com/brettcannon'

bugs.python.org fields:

activity = <Date 2017-03-31.16:36:29.320>
actor = 'dstufft'
assignee = 'Mariatta'
closed = True
closed_date = <Date 2017-02-12.21:19:51.697>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2016-12-10.00:58:56.838>
creator = 'brett.cannon'
dependencies = []
files = ['45846', '45854']
hgrepos = []
issue_num = 28929
keywords = ['patch']
message_count = 18.0
messages = ['282818', '282830', '282866', '282867', '282902', '282937', '282959', '283450', '287592', '287651', '290396', '290397', '290398', '290405', '290441', '290442', '290443', '290444']
nosy_count = 4.0
nosy_names = ['brett.cannon', 'terry.reedy', 'docs@python', 'Mariatta']
pr_nums = ['35', '36', '37', '38', '112', '284', '285', '286', '703', '552']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue28929'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7']

[brettcannon]

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.

[Mariatta]

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`

[brettcannon]

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.

[Mariatta]

Thanks, Brett :) I think it's easier to update the existing Source Link to github. I'll work on a patch for this.

[Mariatta]

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

[brettcannon]

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.

[Mariatta]

Thanks, Brett.

Here's the patch that will work for the 2.7 branch.

[terryjreedy]

Nice idea. I agree with an updated sidebar link, both aesthetically and as a practical matter for doc maintainers.

[brettcannon]

Now that we have migrated to GitHub and Mariatta is a core dev I'm assigning this to her. :)

[Mariatta]

Thanks all :)
PRs have been merged on GitHub.
Closing this.

[Mariatta]

New changeset 23d2c31 by Mariatta in branch '2.7':
[2.7] bpo-28929: Add to Misc/NEWS (GH-286)
23d2c31

[Mariatta]

New changeset 5023686 by Mariatta in branch '3.5':
[3.5] bpo-28929: Add to Misc/NEWS (GH-285)
5023686

[Mariatta]

New changeset 1a8dd94 by Mariatta in branch '3.6':
[3.6] bpo-28929: Add to Misc/NEWS (GH-284)
1a8dd94

[Mariatta]

New changeset e3bf4cd by Mariatta in branch 'master':
bpo-28929: Add to Misc/NEWS (GH-112)
e3bf4cd

[Mariatta]

New changeset f66c81f by Mariatta in branch '3.6':
[backport to 3.6] bpo-28929: Link the documentation to its source file on GitHub (#37)
f66c81f

[Mariatta]

New changeset d4a97d8 by Mariatta in branch 'master':
bpo-28929: Link the documentation to its source file on GitHub (#35)
d4a97d8

[Mariatta]

New changeset e15259c by Mariatta in branch '2.7':
bpo-28929: Link the documentation to its source file on GitHub (#38)
e15259c

[Mariatta]

New changeset cabd1c7 by Mariatta in branch '3.5':
[backport to 3.5] bpo-28929: Link the documentation to its source file on GitHub (#36)
cabd1c7