How to add "Fork me on Github" ribbon using Sphinx and ReadTheDocs theme?

Question

Many open-source projects use a "Fork me on Github" banner at the top-right corner of the pages in the documentation.

To name just one, let's take the example of Python requests:

There is a post on the Github blog about those banners where image code is provided: GitHub Ribbons

But nothing is explained about how to add the link in each of the page generated using Sphinx and then uploaded on ReadTheDocs.

Could you please help to generate this automatically? I expected there could be an option in conf.py but I found none. My Sphinx configuration is the default one.

See here: https://blog.github.com/2008-12-19-github-ribbons/ — quant, Nov 15 '18 at 21:56
@quant I already mentioned this link in my question, but while it provides the `` tag to use, it doesn't explain how to add it to each of the documentation pages generated. — Delgan, Nov 15 '18 at 22:00
@JoranBeasley I just tried it but seems to add the tag as raw html. The [doc](http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog) states that it should be a reST text which will be prepended to each source rather than output file, so I doubt I can work unfortunately. — Delgan, Nov 15 '18 at 22:10

Delgan · Accepted Answer · 2019-05-24T15:48:08.850

The easiest way is to use an alternative theme like alabaster as it comes with preconfigured option like github_banner (see Joran's answer).

For other themes like sphinx-rtd-theme which do not provide such setting, the solution is to rely on Sphinx templating.

One has to create the file docs/_templates/layout.html with the following content:

{% extends '!layout.html' %}
{% block document %}
{{super()}}
    <a href="https://github.com/you">
        <img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub">
    </a>
{% endblock %}

score 4 · Answer 2 · answered Nov 15 '18 at 22:23

4

the great thing about python (especially python on github) is that you can simply look at the source

I can go to https://github.com/requests/requests/blob/master/docs/conf.py and look at their conf.py

where we can see this entry

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
html_theme_options = {
    'show_powered_by': False,
    'github_user': 'requests',
    'github_repo': 'requests',
    'github_banner': True,
    'show_related': False,
    'note_bg': '#FFF59C'
}

we also can notice they are using the theme alabaster

with a quick google we find that alabaster has some docs

https://github.com/mitya57/alabaster-1

github_banner: true or false (default: false) - whether to apply a 'Fork me on Github' banner in the top right corner of the page.

If true, requires that you set github_user and github_repo.
May also submit a string file path (as with logo, relative to $PROJECT/_static/) to be used as the banner image instead of the default.

so the answer is to use alabaster theme and set those options :)

answered Nov 15 '18 at 22:23

Joran Beasley

110,522
12
160
179

Yeah, I realized that too, all doc pages coming up with a "Fork me on Github" banner was using the `alabaster` theme. I still would like to have such banner but using the `rtd` theme. This is the real challenge. I think that should be doable by extending templates, but I need to figure out how exactly. – Delgan Nov 15 '18 at 22:30
take a look at how requests extends the template ... but rtd gives you the "edit on gitlab" link and icon instead ... and is designed around that ... why not just use that? – Joran Beasley Nov 15 '18 at 22:33
I could, but I don't like the "Edit on Git[Hub|Lab]" option because it links to the documentation source page, not the code. As my documentation is automatically generated using the `autodoc` plugin, the link doesn't make much sense, it purpose doesn't fit exactly my needs. – Delgan Nov 15 '18 at 22:46
I think you are overthinking it ... anyone who wants to visit your gitlab/github should dang well be able to navigate easily to the project root ... its not really appropriate for any of the packages to like to their respective `.rst` and yet very large well known projects do ... and I suspect they have zero complaints about it (that said im not trying to discourage you from doing your template thing... i think you just might be over thinking it) – Joran Beasley Nov 15 '18 at 22:56
You are absolutely right. :) But sometimes I can be quite obsessive about something that I want "perfect" while knowing very rationally that it will not affect anyone but me. – Delgan Nov 15 '18 at 23:22

How to add "Fork me on Github" ribbon using Sphinx and ReadTheDocs theme?

2 Answers2