在 sphinx 侧边栏中启用版本阅读文档主题

Question

我想将 versions.html 包含在侧边栏中，但无法成功。

我尝试在 ** 中为侧边栏添加 versions.html，但这没有效果：

html_sidebars = {
    '**': ['versions.html']
}

还有如何在conf.py.

我看过sphinxcontrib-versioning但它并不完全是我正在寻找的。

Answer 1

这可以通过添加一个_templates/versions.html文件来覆盖 rtd 主题的默认jinja 模板文件并向conf.py。

\n

执行以下命令创建新的“_templates/”目录和“versions.html”文件：

\n

mkdir _templates\ncat > _templates/versions.html <<\'EOF\'\n{% if READTHEDOCS or display_lower_left %}\n{# Add rst-badge after rst-versions for small badge style. #}\n  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">\n    <span class="rst-current-version" data-toggle="rst-current-version">\n      <span class="fa fa-book"> Read the Docs</span>\n      v: {{ current_version }}\n      <span class="fa fa-caret-down"></span>\n    </span>\n    <div class="rst-other-versions">\n      {% if languages|length >= 1 %}\n      <dl>\n        <dt>{{ _(\'Languages\') }}</dt>\n        {% for slug, url in languages %}\n          {% if slug == current_language %} <strong> {% endif %}\n          <dd><a href="{{ url }}">{{ slug }}</a></dd>\n          {% if slug == current_language %} </strong> {% endif %}\n        {% endfor %}\n      </dl>\n      {% endif %}\n      {% if versions|length >= 1 %}\n      <dl>\n        <dt>{{ _(\'Versions\') }}</dt>\n        {% for slug, url in versions %}\n          {% if slug == current_version %} <strong> {% endif %}\n          <dd><a href="{{ url }}">{{ slug }}</a></dd>\n          {% if slug == current_version %} </strong> {% endif %}\n        {% endfor %}\n      </dl>\n      {% endif %}\n      {% if downloads|length >= 1 %}\n      <dl>\n        <dt>{{ _(\'Downloads\') }}</dt>\n        {% for type, url in downloads %}\n          <dd><a href="{{ url }}">{{ type }}</a></dd>\n        {% endfor %}\n      </dl>\n      {% endif %}\n      {% if READTHEDOCS %}\n      <dl>\n        <dt>{{ _(\'On Read the Docs\') }}</dt>\n          <dd>\n            <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _(\'Project Home\') }}</a>\n          </dd>\n          <dd>\n            <a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _(\'Builds\') }}</a>\n          </dd>\n      </dl>\n      {% endif %}\n      <hr/>\n      {% trans %}Free document hosting provided by <a href="http://www.readthedocs.org">Read the Docs</a>.{% endtrans %}\n \n    </div>\n  </div>\n{% endif %}\n \nEOF\n

\n

并执行以下命令附加到conf.py文件中：

\n

cat >> conf.py <<\'EOF\'\n \n############################\n# SETUP THE RTD LOWER-LEFT #\n############################\ntry:\n   html_context\nexcept NameError:\n   html_context = dict()\nhtml_context[\'display_lower_left\'] = True\n\ntemplates_path = [\'_templates\']\n\nif \'REPO_NAME\' in os.environ:\n   REPO_NAME = os.environ[\'REPO_NAME\']\nelse:\n   REPO_NAME = \'\'\n \n# SET CURRENT_LANGUAGE\nif \'current_language\' in os.environ:\n   # get the current_language env var set by buildDocs.sh\n   current_language = os.environ[\'current_language\']\nelse:\n   # the user is probably doing `make html`\n   # set this build\'s current language to english\n   current_language = \'en\'\n \n# tell the theme which language to we\'re currently building\nhtml_context[\'current_language\'] = current_language\n \n# SET CURRENT_VERSION\nfrom git import Repo\nrepo = Repo( search_parent_directories=True )\n \nif \'current_version\' in os.environ:\n   # get the current_version env var set by buildDocs.sh\n   current_version = os.environ[\'current_version\']\nelse:\n   # the user is probably doing `make html`\n   # set this build\'s current version by looking at the branch\n   current_version = repo.active_branch.name\n \n# tell the theme which version we\'re currently on (\'current_version\' affects\n# the lower-left rtd menu and \'version\' affects the logo-area version)\nhtml_context[\'current_version\'] = current_version\nhtml_context[\'version\'] = current_version\n \n# POPULATE LINKS TO OTHER LANGUAGES\nhtml_context[\'languages\'] = [ (\'en\', \'/\' +REPO_NAME+ \'/en/\' +current_version+ \'/\') ]\n \nlanguages = [lang.name for lang in os.scandir(\'locales\') if lang.is_dir()]\nfor lang in languages:\n   html_context[\'languages\'].append( (lang, \'/\' +REPO_NAME+ \'/\' +lang+ \'/\' +current_version+ \'/\') )\n \n# POPULATE LINKS TO OTHER VERSIONS\nhtml_context[\'versions\'] = list()\n \nversions = [branch.name for branch in repo.branches]\nfor version in versions:\n   html_context[\'versions\'].append( (version, \'/\' +REPO_NAME+ \'/\'  +current_language+ \'/\' +version+ \'/\') )\n \n# POPULATE LINKS TO OTHER FORMATS/DOWNLOADS\n \n# settings for creating PDF with rinoh\nrinoh_documents = [(\n master_doc,\n \'target\',\n project+ \' Documentation\',\n \'\xc2\xa9 \' +copyright,\n)]\ntoday_fmt = "%B %d, %Y"\n \n# settings for EPUB\nepub_basename = \'target\'\n \nhtml_context[\'downloads\'] = list()\nhtml_context[\'downloads\'].append( (\'pdf\', \'/\' +REPO_NAME+ \'/\' +current_language+ \'/\' +current_version+ \'/\' +project+ \'-docs_\' +current_language+ \'_\' +current_version+ \'.pdf\') )\n \nhtml_context[\'downloads\'].append( (\'epub\', \'/\' +REPO_NAME+ \'/\' +current_language+ \'/\' +current_version+ \'/\' +project+ \'-docs_\' +current_language+ \'_\' +current_version+ \'.epub\') )\n \nEOF\n

\n

请参阅此网站的示例：

\n

\n
• https://maltfield.github.io/rtd-github-pages/
\n

\n

可以从以下 GitHub 存储库查看（并轻松分叉）创建上述站点的整个配置：

\n

\n
• https://github.com/maltfield/rtd-github-pages/
\n

\n

有关如何设置的更多信息，请参阅这篇文章，了解如何设置左下角的“阅读文档”菜单以在语言、版本和下载之间进行导航。

\n