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

Question

我想在侧边栏中包含 versions.html 并且无法成功。

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

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

还有如何在 conf.py中声明不同的版本.

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

Answer 1

这可以通过添加 _templates/versions.html 来实现。文件覆盖 rtd 主题的默认值 jinja template file并向 conf.py 添加一些变量文件。
执行以下命令来创建一个新的 '_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文件:

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/

可以从以下 GitHub 存储库查看(并轻松 fork )创建上述站点的整个配置:

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

有关我如何设置的更多信息，请参阅此 article on how to setup the lower-left Read the Docs menu for navigation between languages and versions and downloads .