2

I'd like to add a simple warning directive at the top of every page on a Sphinx RTD site:

.. 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!

What's the simplest way to do this? I'm using the sphinx_rtd_theme.

I can see how to add a block using the extrabody block, but it appears outside the main content area and is positioned and styled totally independently.

Ideally, I'd want this block to show up at an attention directive just below the breadcrumbs on every page.

Abe
  • 22,738
  • 26
  • 82
  • 111
  • 1
    Here's other examples to consider: https://docs.pylonsproject.org/projects/pyramid/en/master/ and https://docs.pylonsproject.org/projects/pyramid/en/1.9-branch/ You could either edit the theme with actual HTML, or you put that reStructuredText into an included file, and add an `include` directive at the top of each .rst file. Not the prettiest method, but it would get the job done. – Steve Piercy May 14 '20 at 13:46

2 Answers2

4

You could add this to the conf.py Sphinx configuration file:

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

and it will be included at the beginning of every source file that is read ‒ see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog.

F-string literals work too, so f'This is release #{release}' will substitute that variable value.

Apropos
  • 856
  • 5
  • 11
  • 1
    Also, some themes include this functionality, e.g. "announcement banners" in [sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/en/stable/customize/announcements.html) – Apropos Jun 27 '22 at 20:40
1

This isn't the advice anyone wants to hear. But... consider switching to another theme that supports common functionality like this out-of-the-box: e.g.,

  • pydata-sphinx-theme, widely used throughout the open-source data science community. This includes NumPy and SciPy. It doesn't get bigger than that. Personally, I recently switched a sorta popular project I maintain from Furo (...which I strongly advise against, as it's even less configurable than the sphinx-rtd-theme you're currently using) to pydata-sphinx-theme. I wish I'd switched sooner. pydata-sphinx-theme single-handedly catapults Sphinx to the upper crust of the documentation generation community. It's so expert at everything that I kinda wish Sphinx just bundled pydata-sphinx-theme as its default theme. Seriously. That would've saved me a great deal of grief. Why bother with anything else in 2023 and beyond?
  • sphinx-book-theme, which is actually built on top of pydata-sphinx-theme. It's pydata-sphinx-theme++, effectively. If you know one, you know the other.

Both trivialize the injection of arbitrary HTML (referred to as an "announcement") at the top of every page:

# In your project's equivalent of "docs/conf.py":
html_theme_options = {
    # Announcement banner defined as a string of arbitrary HTML, temporarily
    # displayed at the top of each page until the user begins scrolling.
    'announcement': (
        "<p>"
        "Here's a <a href='https://pydata.org'>PyData Announcement!</a>"
        "</p>"
    ),

    ...
}

HTML is much more useful than mere reStructuredText (reST) in this context of a project banner. HTML admits the possibility of exotic use cases like project-specific advertising – which almost certainly violates the Terms of Services on free-as-in-beer Sphinx hosts like ReadTheDocs (RTD), so please avoid abusing this there. Still, this feature is pretty much the Ultimate Power for informing users about... well, anything!

But, But... What About rst_prolog?

Yeah. Don't do that. Technically, you can force-feed an announcement at the top or bottom of every page by abusing Sphinx's standard rst_prolog and rst_epilog globals as in the accepted answer. Pragmatically, doing so doesn't actually produce a hero banner; it's just a crude hack.

You ideally want your announcement to be an actual banner that sprawls across the full horizontal width of each page. But the output produced by the rst_prolog and rst_epilog globals is almost always confined to the central column of your theme. It just looks like any other normal page content. It's certainly better than nothing, but announcements are intended to immediately draw the eye. So, do so!

In short, may the PyData be with you always. \o/

Cecil Curry
  • 9,789
  • 5
  • 38
  • 52