NEW: Adding announcement banners #722
Conversation
|
So if I'm reading this right, the only way to add/change an announcement is to rebuild the docs? The functionality I'd love to have built-in is to add/remove the announcement by editing a file in the base of the docs repo. That way even old/stable versions get the announcement. Not sure if that's compatible with your vision for it, though. |
|
One way to do what you describe would be to just follow that workflow yourself, and read in the text file via conf.py then insert it into that keyword value. You could then add a step that downloads the latest version of the text file at build time. Though, you'd still need to rebuild the docs. I guess the only way to do it without rebuilding docs would be to do something like the version drop-down, that used JavaScript to read a text file at page load time. I'm not really sure how to do that in a nice way w the CSS though...maybe it could be a follow up PR |
|
Sure. So what I have right now has extended the theme to put in an empty div and then have javascript that looks for a non-empty |
|
Thinking about @dopplershift's request, what if we supported something like this:
|
|
I think that the latest commit will add this functionality. It works kinda like the version switcher now, though only if |
|
That sounds great to me! Thanks, this is one less thing we have to tweak the theme to add. |
|
@12rambau wanna take another quick look to make sure you're +1 on the URL-based approach this now supports as well? |
docs/user_guide/configuring.rst
Outdated
| You can add an announcement banner that draws extra attention from your reader. | ||
| It will be displayed at the top of the screen, but will disappear once you start scrolling. | ||
|
|
||
| To add an announcement banner, use the ``html_theme_options.announcement`` configuration. |
There was a problem hiding this comment.
shouldn't these be html_theme_options['announcement'] (rather than the dot syntax)? It is a python dictionary after all.
| {%- if is_remote %} | ||
| <script> | ||
| $.get("{{ theme_announcement }}", success=(data)=>{ | ||
| console.log(data); |
There was a problem hiding this comment.
question: is this considered JS best practice (to console.log on successful get)? Or is this cruft left over from the process of developing this feature? (I honestly don't know, but my instinct would be to only log the failures)
There was a problem hiding this comment.
if that's the case I need to edit the theme code as well I think I'm consol.log every time the mode is changed
There was a problem hiding this comment.
I think that it's fine to do this when the theme mode is changed, but in this case it was cruft haha
src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html
Outdated
Show resolved
Hide resolved
docs/conf.py
Outdated
| @@ -108,6 +108,8 @@ | |||
| }, | |||
| "use_edit_page_button": True, | |||
| "show_toc_level": 1, | |||
| # "announcement": "Here's a test <a href='https://google.com'>announcement</a>!", | |||
| "announcement": "https://raw.githubusercontent.com/choldgraf/pydata-sphinx-theme/header/docs/_templates/custom-template.html", | |||
There was a problem hiding this comment.
should choldgraf change to pydata here before merging?
src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html
Outdated
Show resolved
Hide resolved
Co-authored-by: Daniel McCloy <dan@mccloy.info>
|
I believe I've addressed @drammock's ideas! |
Co-authored-by: Daniel McCloy <dan@mccloy.info>
|
OK I think this one is ready to go - anybody want to hold off or shall we give it a whirl? :-) |
This adds functionality for announcement banners. This lets theme authors define some text that shows up at the top of the page, and disappears as somebody scrolls down. It uses the same CSS hack we use for admonitions in order to color the background by the primary color. It also cleans up some CSS rules that makes our CSS a bit less hacky :-)
Here's how it looks with a little demo:
I didn't add a test for this mostly because the functionality is purely in the templates and there isn't really much extra functionality to text (the HTML shows up or it doesn't, that's it), but I'm happy to add a test if folks think it'd be helpful.