ENH: link to gh source w/ ext.viewcode and/or ext.linkcode

[westurner]

Is your feature request related to a problem? Please describe. As a docs reader, I want to read the source in the viewcode interface and then open it in {Github, Gitlab,}.

Describe the solution you'd like

• [ ] Another config option (?) like sphinx.ext.linkcode but simpler:

  • f'{placeholders}/if' it's not a callable?

  • please feel free to just rip from or merge from e.g. sphinxcontrib-srclinks, which expands to HTTPs and SSH urls from conf.py values

    • https://github.com/westurner/sphinxcontrib-srclinks/blob/2052cf53b725e94a0ba8da694fe2b3eef12045ff/sphinxcontrib/srclinks/__init__.py#L236-L264
    • https://github.com/westurner/sphinxcontrib-srclinks#usage:

      # conf.py
      # srclink settings
      srclink_project = 'https://github.com/westurner/sphinxcontrib-srclinks'
      #srclink_project = 'https://bitbucket.org/westurner/sphinxcontrib-srclinks'
      #srclink_project = 'hg@bitbucket.org/westurner/sphinxcontrib-srclinks'
      #srclink_project = 'git@bitbucket.org/westurner/sphinxcontrib-srclinks'
      srclink_src_path = 'docs/'
      #srclink_src_path = ''
      srclink_branch = 'master'
      #srclink_branch = 'develop'

    • https://github.com/westurner/sphinxcontrib-srclinks/blob/master/sphinxcontrib/srclinks/__init__.py#L445 tests :

      
      test_html_page_context(              ## conf.py: srclink_%s
      "github.com/westurner/dotfiles",  # project
      "develop",                        # project_branch
      "doc/",                           # project_src_path
      "westurner/dotfiles",             # project_path
      project_url="https://github.com/westurner/dotfiles",
      project_https_url="https://github.com/westurner/dotfiles",
      project_ssh_url="ssh://git@github.com/westurner/dotfiles",
      project_native_url="git://github.com/westurner/dotfiles")

    test_html_page_context( "westurner/dotfiles", "develop", "doc/", "westurner/dotfiles", project_url="https://github.com/westurner/dotfiles", project_https_url="https://github.com/westurner/dotfiles", project_ssh_url="ssh://git@github.com/westurner/dotfiles", project_native_url="git://github.com/westurner/dotfiles")

    test_html_page_context( "https://github.com/westurner/dotfiles", "develop", "doc/", "westurner/dotfiles", project_https_url="https://github.com/westurner/dotfiles", project_ssh_url="ssh://git@github.com/westurner/dotfiles", project_native_url="git://github.com/westurner/dotfiles")

    test_html_page_context( "https://bitbucket.org/westurner/dotfiles",

    
    - https://github.com/westurner/sphinxcontrib-srclinks/blob/master/sphinxcontrib/srclinks/_templates/srclinks.html
    - \[ ] better usage docs (&or argparse) for the `__main__`
    - [ ] MRG: merge config, templates with viewcode ?
    - [ ] MRG: merge config with linkcode ?
    - [ ] MRG: merge config with extlinks ?

Describe alternatives you've considered

• https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/linkcode.py
  • https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html
• https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/viewcode.py
  • https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html
• https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/extlinks.py
  • https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
• https://github.com/westurner/sphinxcontrib-srclinks/blob/master/sphinxcontrib/srclinks/__init__.py#L445

Additional context :space_invader:

[elliottower]

this would be a really awesome feature, as you mention it seems like it should be possible using linkcode and viewcode it's possible to do edit buttons on documentation pages that bring you to the github markdown file, would be great to have links to full source files as well

[rainbowphysics]

Hey all, I wrote a gist today that could be adapted as a solution to this issue: https://gist.github.com/rainbowphysics/505e35a7a1e9545d5a6cde22f6ca9558

[rainbowphysics]

@pv If we went ahead with implementing this functionality, would you prefer it: integrated into sphinx.ext.linkcode, or added as a new ext module?