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.

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

"Edit on GitHub" to multiple URLs. #1560

Open
vhdumann opened this issue May 3, 2024 · 0 comments
Open

"Edit on GitHub" to multiple URLs. #1560

vhdumann opened this issue May 3, 2024 · 0 comments

Comments

@vhdumann
Copy link

vhdumann commented May 3, 2024

TL;DR: How can I set different GitHub URLs relative and specific to toc chapters / directories.
Or a step back: What is the best way to combine multiple sphinx documentations from different repositories into one single project.

Context

I have multiple sphinx documentations for different projects across separate GitHub repositories.
I want to create one main project where all other projects are included for easier navigation, searchability across projects, etc.
For this I created a new sphinx project, copied the other projects into subdirectories and included them via a new root TOC. This works nicely.

Problem: "Edit on GitHub"

Documentation

First of all I think this feature is missing from the rtd theme documentation.
Only github_url is mentioned.
The more useful approach is only documented in the readthedocs service documentation.

Solutions

I thought about different solutions,

  1. The sphinx meta data solution :github_url: <url> needs to be defined in every file to redirect to the correct repository. This variable does not use branches, file names, ... Therefore one would have to define the unique URL in every file.
  2. Using html_context with github_user, github_host etc. creates the URLs dynamically (that is with the configured branch, the actual file name and so on). But html_context is global, I can not use different hosts or branches from separate repositories.
  3. Writing a custom extension. Somehow modifying each file during the build process as necessary.

It seems like I can not avoid customizing sphinx / the theme for this usecase. What do you think?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant