Hi there, having seen your recent tweet I wanted to give this package (thanks for developing it!) a shot at https://github.com/autoreject/autoreject/pull/251.

I did the following:

• pip-installed sphinx-github-role in my doc build job
• added the following to my conf.py: github_default_org_project = ("autoreject", "autoreject")
• used the following syntax in my changelog:

:github:`#225`

Yet, the rendered docs look broken.

And the build log gives me an error:

Using in RST: Unknown interpreted text role "github".

Can you see what's going wrong? Is that some user error of mine? Or something with sphinx-github-role?

Fixes #17

This implements the change I described in #17.

There was one required change to an existing test, since what was previously a malformed link now could now be a reference to a GitHub repository. This has produced a different failure message.

I've not spent a ton of time working with Python projects before, so let me know if there's anything you'd like changed.

I'd like to use this role to be able to link directly to GitHub projects, rather than just to specific issues within the projects.

For example:

:github:`astrojuanlu/sphinx-github-role`

would link to this repository, without requiring an issue to be specified.

I'm documenting a project with different components across a variety of repositories, so a shorthand syntax for referencing specific repositories would be helpful.

In the same way that folks can do

{ref}`doc`
{ref}`My document <doc>`

it would be cool if we could allow

{github}`#13`
{github}`PR #13 <#13>`

1. docs don't seem to have easy link back to github.

2. Do you think that non-github / gitlab will be a potential extensions, so you can just do :issue:`#31` regardless of the vcs, and this leads to

3. Do you believe there could be a project mapping org -> github|gitlab, so that :issue:`projongithub#31` and :issue:`projongitlab#31`

4. which is not dependent of previous ones, I'd love to have some standardization and use the same extensions on many projects of the scientific ecosystem, and I can try to replace the one we use in IPython when you belive this is ready enough.

Wouldn't it be cool if we could show a modal or tooltip with these cool social media previews?

(source: https://cards-dev.twitter.com/validator)

Content:

<meta name="twitter:image:src" content="https://opengraph.githubassets.com/d0b6e212f5531e99b4deb14274afa748ddb99ff75bc5d1d8e28d1034ffa2e62d/poliastro/poliastro/pull/1184" /><meta name="twitter:site" content="@github" /><meta name="twitter:card" content="summary_large_image" /><meta name="twitter:title" content="Move flyby computation to core by Yash-10 · Pull Request #1184 · poliastro/poliastro" /><meta name="twitter:description" content="This PR tries to move computations for threebody flybys to core.
Thanks!" />

pinging @humitos as my local sphinx-hoverxref expert, and @choldgraf because I've seen you mention this topic a few times on Twitter

The cool thing about the current approach is that URLs with /issues redirect to /pull if the ID corresponds to a pull request. See it in action:

https://github.com/astrojuanlu/sphinx-github-role/issues/2 (https://github.com/astrojuanlu/sphinx-github-role/issues/2)

However, it might "look bad" to have these URLs pointing to issues that are, in fact, pull requests. To my knowledge, the only way to disambiguate this is to make an API call:

$ curl -s -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/astrojuanlu/sphinx-github-role/issues/2 | jq '.["pull_request"]["html_url"]'
"https://github.com/astrojuanlu/sphinx-github-role/pull/2"
$ curl -s -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/astrojuanlu/sphinx-github-role/issues/4 | jq '.["pull_request"]["html_url"]'
null

I wonder if it's worth the hassle?

Pros:

• Always uses correct-looking URL

Cons:

• Can be slow
• Can be unreliable
• Might be rate-limited
• Might require an API key