Link to project repository

[thibaudcolas]

On a lot of Sphinx projects on Read the Docs, when browsing the project’s docs, it’s really hard to go from there to the project’s repository in GitHub or other platforms?

I’m not sure if this is something to fix specifically in this theme, or perhaps via the Read the Docs Flyout menu. But it’s such a common pain point that it’d be nice to have a recipe that works well across a wide range of sites.

Example

In my mind this is an issue across a lot of packages / docs sites in the Python ecosystem, but here’s a specific example to illustrate:

I don’t think sphinx-rtd-theme has a link to its GitHub repository anywhere in its docs? (aside from the "theme" link, which is an oddity specific to this project). To go from the docs to the repo, I have to:

1. Open the RTD flyout menu.
2. Go to the Project home.
3. Toggle the "More project information" area in the header.
4. Click the Repository link https://github.com/readthedocs/sphinx_rtd_theme.

Another example is django-treebeard. Here we have the "Edit on GitHub" link, so I know I can click on that. I have no intention to edit anything, but I know from there I can go to the repository root / issues / etc.

Fixing this

I don’t really know what’s the best way? I assume Read the Docs knows which service / repository any automated builds come from, makes that available via environment variables, and a theme like this one could use that information to display a link with text "Repository" or "GitHub" or similar, either in the header area, sidebar, or worst case footer.

This might also be configurable via Sphinx config for those who prefer that? Happy to hear any other ideas. I’d really like to find ways that make this easy to fix across hundreds of existing projects.

[melissawm]

One very simple solution would be to add the repo link to the left-hand sidebar (e.g. the following screenshot)

I would also be happy to see this feature, and would be happy to send in a PR if folks agree on a solution (sidebar vs. flyout menu vs. something else)

[jdillard]

I think the Flyout might be better in this case since it is theme agnostic. There is a view_url, but unsure where/how that gets set.

[stsewd]

Not exactly the same, but you can add an "edit on github" link on each page https://docs.readthedocs.com/platform/stable/guides/edit-source-links-sphinx.html.

I'll be +1 on just linking to the repo from the flyout (not the exact path on the repo).

here is a view_url, but unsure where/how that gets set.

Looks like dead code, we don't return that from the API.

[humitos]

We are performing a re-work of the flyout/addons UI in https://github.com/readthedocs/addons/issues/574. It's planned to include the link to the VCS repository there. We haven't started yet, but it's in our roadmap to start with it sooner than later.