如何使用 Sphinx 和 ReadTheDocs 主题添加 "Fork me on Github" 功能区？

Question

许多开源项目在文档页面的右上角使用“在 Github 上分叉我”横幅。

仅举一个例子，让我们以 Python requests:

为例

Github 博客上有一个 post 关于提供图像代码的横幅：GitHub Ribbons

但是没有解释如何在使用 Sphinx 生成然后上传到 ReadTheDocs 的每个页面中添加 link。

你能帮忙自动生成吗？我预计 conf.py 中可能会有一个选项，但我发现 none。我的 Sphinx 配置是默认配置。

Answer 1

python（尤其是 github 上的 python）的优点在于您可以简单地查看源代码

我可以去https://github.com/requests/requests/blob/master/docs/conf.py看看他们的conf.py

我们在哪里可以看到这个条目

# 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'
}

我们还可以注意到他们使用的主题是 alabaster

快速 google 我们发现 alabaster 有一些文档

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.

所以答案是使用雪花石膏主题并设置这些选项:)

Answer 2

最简单的方法是使用替代主题，例如 alabaster as it comes with preconfigured option like github_banner (see )。

其他主题如sphinx-rtd-theme没有提供这样的设置，解决方法是依赖Sphinx templating.

必须创建包含以下内容的文件 docs/_templates/layout.html：

{% 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 %}

如何使用 Sphinx 和 ReadTheDocs 主题添加 "Fork me on Github" 功能区？

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

python

github

python-sphinx

read-the-docs