Edit on Github button

[capsia37]

Hi, I'm migrating a documentation from the sphinx_rtd_theme to furo. This theme is awesome but it's missing the possibility edit the page on github directly from the docs website. This is very useful in collaborative projects. Are there any plans to implement this?

Thank you!

[pradyunsg]

This is technically added by ReadTheDocs, if you're deploying your documentation there. That said, I definitely think this would be a good addition to the theme. A PR adding this to the current footer would be very welcome!

I just "distracted" away from working on this theme for a bit, by https://github.com/pradyunsg/sphinx-basic-ng/ to revamp more of the Sphinx theme ecosystem at the moment. :)

[ebassi]

Are there any news on this?

[pradyunsg]

Not yet, no.

[ebassi]

Thanks for your reply; I'd be interested to look into it—the GNOME documentation team is currently using Furo and Sphinx for the new developers documentation and human interface guidelines websites, and we'd very much like to link to the pages on gitlab.gnome.org to improve the contribution workflow.

[pradyunsg]

I wrote a rough implementation for this, a few months ago in https://github.com/pradyunsg/sphinx-basic-ng/blob/main/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html. That doesn't handle custom instances of gitlab though, mostly because I don't know what supporting them should look like. :/

Most of my personal projects are hosted on ReadTheDocs, which adds a clear embed with "edit this page" links (see v: stable in the bottom right on https://pip.pypa.io/en/stable/).

[ebassi]

The configuration keys in sphinx-basic-ng are good enough to build the final URL of the source file; you can keep the current matching for opening the web editing UI for well known hosting sites, and for custom hosts you just point to the file in the repository:

<a href="{{ source_repository }}/tree/{{ source_branch }}/{{ document_path }}">edit this page</a>

Users can then edit the file manually.

[capsia37]

Hi, I've been searching for the best position for the button in the last few days, I think it would fit best at the bottom of the sidebar. I came to this conclusion because it is easier to find than the footer button. This is a very important feature for a community contributed documentation. I've already made most of the changes as overrides to the theme in our project, but it would be great if we can contribute these features directly to the theme and enable them as options.

I've also thought that the right sidebar could be customizable as the left one. I think it would be a nice place to link to translated pages, edit on git and maybe someone could also add their own components to it without fully overriding the sidebar.

I have a public preview at Readthedocs if you'd like to see how it looks:
https://ubports-docs-dev.readthedocs.io/en/latest/userguide/install.html

Thank you!

[Jackenmen]

I think that this could be solved by making the "Show source" link at the bottom point to GitHub instead of the _sources directory if configured appropriately. I don't think the text should change from "Show source" to "Edit on GitHub" as personally I more often use the "Edit on GitHub" link to show source, not to actually edit the document. It is what sphinx-rtd-theme does though.

[kandahk]

Was this added to furo theme? We need to add it furo based docs, can I get how it can be done?

[pradyunsg]

This has been added in 76b7e73, and will be in the next release. :)

[pradyunsg]

See also https://pradyunsg.me/furo/customisation/edit-button/

[eddyashton]

@pradyunsg Thanks for adding this! We recently hacked in a button ourselves, but we'd love to use one directly from the theme if possible.

Is there a reason why this edit button and the show source button are gated by READTHEDOCS? It seems they only rely on the various github_* entries in html_context, and those are also checked explicitly. So if we set those variables correctly in conf.py, why do we also need READTHEDOCS?

[pradyunsg]

Because I don't want users to consider providing variables to treat html_context as an extension point for this theme -- there is one way to do that already: html_theme_options.

I plan to add theme options to allow setting this in the future -- but haven't come around to it yet.

[Jackenmen]

I see that "Show source" is now gone. I would prefer for it to link to GitHub source (with ?plain=1 to force a non-rendered view of the RST file) rather than raw source text hosted from _sources but regardless, I still think it has a purpose. Going through the edit button to then click "Cancel changes" and switch to source blob to actually be able to see a properly syntax-highlighted RST file is IMO an annoyance if you do it often.

[Jackenmen]

To not be all negative though, I certainly like how you fit the edit button into the design, it's just not what I personally am looking for 😄

[pradyunsg]

See #374 for the footer design changes, which includes the rationale for the Show source changes.

[aantn]

Hey, I'd like to get support for this outside of Read the Docs. What would be involved in doing so? We (robusta.dev) would be happy to help out as we use Furo (see our docs) and would really like this feature.

[pradyunsg]

The work needed for this is:

• Migrate Furo to inherit from basic-ng (https://github.com/pradyunsg/sphinx-basic-ng/) instead of basic from Sphinx itself.
• Use components/edit-this-page.html, except with an override to preserve the current RTD behaviour and change the default {{ _("Edit this page") }} prompt to the button that Furo is using.

[aantn]

Got it. Migrating Furo is a bit more than we can take on right now.
Let me know if we can help with something else.

[domdfcoding]

I don't know if it's something specific to the packaging docs, but clicking the edit button on https://packaging.pypa.io/en/stable/specifiers.html goes to https://github.com/pypa/packaging/edit/d563917280d65a6ce2e622bd3d07438e1ee259f3/docs/specifiers.rst, which is a 404. d563917 is the commit the docs were built for, but I don't think GitHub allows edit URLs for specific commits. Furo gets the commit sha or branch name from ReadTheDocs and builds the URL from that.

[aaugustin]

The same issue was reported here: python-websockets/websockets#1365

[pradyunsg]

Oof, that's slightly annoying. Filed #668 for this.