Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Provide a link from documentation back to its source file #73115

Closed
brettcannon opened this issue Dec 10, 2016 · 18 comments
Closed

Provide a link from documentation back to its source file #73115

brettcannon opened this issue Dec 10, 2016 · 18 comments
Assignees
@Mariatta
Labels
3.7 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@brettcannon
Copy link
Member

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
    Copy link
    Member Author

    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.

    @brettcannon brettcannon added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Dec 10, 2016
    @Mariatta
    Copy link
    Member

    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
    Copy link
    Member Author

    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
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

    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
    Copy link
    Member Author

    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
    Copy link
    Member

    Thanks, Brett.

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

    @terryjreedy
    Copy link
    Member

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

    @brettcannon
    Copy link
    Member Author

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

    @brettcannon brettcannon assigned Mariatta and unassigned docspython Feb 11, 2017
    @Mariatta Mariatta added the 3.7 (EOL) end of life label Feb 12, 2017
    @Mariatta
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

    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
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

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

    @Mariatta
    Copy link
    Member

    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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees

    @Mariatta Mariatta

    Labels
    3.7 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @brettcannon @Mariatta @terryjreedy