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

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

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

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

另外如何声明不同的版本conf.py.

我看过sphinxcontrib 版本控制 https://github.com/Robpol86/sphinxcontrib-versioning但这并不正是我正在寻找的。

这可以通过添加一个来实现_templates/versions.html文件覆盖 rtd 主题的默认值jinja 模板文件 https://www.sphinx-doc.org/en/master/templating.html并向其中添加一些变量conf.py file.

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

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

并执行以下命令附加到conf.py file:

cat >> conf.py <<'EOF'
 
############################
# SETUP THE RTD LOWER-LEFT #
############################
try:
   html_context
except NameError:
   html_context = dict()
html_context['display_lower_left'] = True

templates_path = ['_templates']

if 'REPO_NAME' in os.environ:
   REPO_NAME = os.environ['REPO_NAME']
else:
   REPO_NAME = ''
 
# SET CURRENT_LANGUAGE
if 'current_language' in os.environ:
   # get the current_language env var set by buildDocs.sh
   current_language = os.environ['current_language']
else:
   # the user is probably doing `make html`
   # set this build's current language to english
   current_language = 'en'
 
# tell the theme which language to we're currently building
html_context['current_language'] = current_language
 
# SET CURRENT_VERSION
from git import Repo
repo = Repo( search_parent_directories=True )
 
if 'current_version' in os.environ:
   # get the current_version env var set by buildDocs.sh
   current_version = os.environ['current_version']
else:
   # the user is probably doing `make html`
   # set this build's current version by looking at the branch
   current_version = repo.active_branch.name
 
# tell the theme which version we're currently on ('current_version' affects
# the lower-left rtd menu and 'version' affects the logo-area version)
html_context['current_version'] = current_version
html_context['version'] = current_version
 
# POPULATE LINKS TO OTHER LANGUAGES
html_context['languages'] = [ ('en', '/' +REPO_NAME+ '/en/' +current_version+ '/') ]
 
languages = [lang.name for lang in os.scandir('locales') if lang.is_dir()]
for lang in languages:
   html_context['languages'].append( (lang, '/' +REPO_NAME+ '/' +lang+ '/' +current_version+ '/') )
 
# POPULATE LINKS TO OTHER VERSIONS
html_context['versions'] = list()
 
versions = [branch.name for branch in repo.branches]
for version in versions:
   html_context['versions'].append( (version, '/' +REPO_NAME+ '/'  +current_language+ '/' +version+ '/') )
 
# POPULATE LINKS TO OTHER FORMATS/DOWNLOADS
 
# settings for creating PDF with rinoh
rinoh_documents = [(
 master_doc,
 'target',
 project+ ' Documentation',
 '© ' +copyright,
)]
today_fmt = "%B %d, %Y"
 
# settings for EPUB
epub_basename = 'target'
 
html_context['downloads'] = list()
html_context['downloads'].append( ('pdf', '/' +REPO_NAME+ '/' +current_language+ '/' +current_version+ '/' +project+ '-docs_' +current_language+ '_' +current_version+ '.pdf') )
 
html_context['downloads'].append( ('epub', '/' +REPO_NAME+ '/' +current_language+ '/' +current_version+ '/' +project+ '-docs_' +current_language+ '_' +current_version+ '.epub') )
 
EOF

请参阅此网站的示例：

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

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

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

有关如何设置的更多信息，请参阅此有关如何设置左下阅读文档菜单以在语言、版本和下载之间进行导航的文章 https://tech.michaelaltfield.net/2020/07/23/sphinx-rtd-github-pages-2/.