在 Sphinx RTD 站点的每个页面顶部添加警告指令答案

【问题标题】：Add a warning directive at the top of every page on a Sphinx RTD site在 Sphinx RTD 站点的每个页面顶部添加警告指令
【发布时间】：2020-05-14 13:34:29
【问题描述】：

我想在 Sphinx RTD 网站的每个页面顶部添加一个简单的警告指令：

.. attention::

  The next major release of this project will launch on X date.
  In the meantime, we're looking for feedback.
  If you'd like an early preview, please reach out at someemail@someaddress.com!

最简单的方法是什么？我正在使用sphinx_rtd_theme。

我可以看到如何使用 extrabody 块添加块，但它出现在主要内容区域之外，并且完全独立地定位和设置样式。

理想情况下，我希望此块显示在每个页面上面包屑下方的注意指令中。

【问题讨论】：

这里还有其他例子要考虑：docs.pylonsproject.org/projects/pyramid/en/master 和 docs.pylonsproject.org/projects/pyramid/en/1.9-branch 您可以使用实际的 HTML 编辑主题，或者将 reStructuredText 放入包含的文件中，然后在每个 .rst 文件的顶部。不是最漂亮的方法，但它可以完成工作。

标签： python-sphinx restructuredtext read-the-docs

【解决方案1】：

您可以将其添加到conf.py Sphinx 配置文件中：

rst_prolog = """.. attention::
    The next major release is imminent.
"""

它将包含在每个读取的源文件的开头 ‒ 参见 https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog。

F-string 字面量也可以，所以f'This is release #{release}' 将替换该变量值。

【讨论】：