search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.53k stars 2.12k forks source link

Custom style for Read the Docs floating flyout will stop working #12675

Open humitos opened 3 months ago

humitos commented 3 months ago

Hi 👋🏼 -- I'm sorry I'm opening a feature request, but I wasn't sure what was a better fit for this notice.

I noticed that you are styling the Read the Docs floating flyout at the bottom right of the screen via CSS and I wanted to let you know that we are making some changes in the Read the Docs build process that will affect that style customization.

The customization I found happens in https://github.com/sphinx-doc/sphinx/blob/master/doc/_themes/sphinx13/static/sphinx13.css#L624-L648

There are 2 things to notice here:

  1. Read the Docs currently injects some extra configurations in the Sphinx's conf.py during the build.
  2. The flyout is injected at serve time via JavaScript hitting a /footer_html/ endpoint and injecting the blob HTML returned by it into the page.

I'm opening this issue here to notify that both patterns are now deprecated and will be removed. Read the full announcement in https://github.com/readthedocs/readthedocs.org/issues/11474 for more details about this.

I understand that 1) does not affect you because Sphinx's documentation is not depending on that context injection as far as I can tell (but you may want to double check that).

On the other hand, 2) does affect this project's documentation because the new default flyout (implemented as a Read the Docs Addon -- using WebComponents) does not allow this type of customization yet. However, the exact same data used to generate it is exposed as a JSON-like object that you can use to generate the flyout as you like; keeping it in the same floating position or even integrate it more in the navbar or header (as you prefer).

You can test how the new flyout looks like by enabling addons in your project.

Let me know if this is clear enough or if you have any doubt. I'm happy to help with this process if I can.

chrisjsewell commented 2 months ago

Thanks for the update @humitos, indeed I was aware of this; I added the styling in https://github.com/sphinx-doc/sphinx/pull/12457 as a quick and dirty improvement, to make it not stand out so much.

But ideally, I want it to eventually be like furo and/or sphinx-book-theme, whereby it is integrated at the bottom of the left navigation column (see e.g. https://github.com/pradyunsg/furo/issues/795)

Would you be interested in proposing a PR to change it?

humitos commented 2 months ago

Would you be interested in proposing a PR to change it?

I'm happy to help you with the JavaScript integration that generates the flyout if somebody else builds the HTML layout and CSS styles for the positioning (I'm not really good at that and it could take me forever). I've already done this work with the Read the Docs theme re-using the existing HTML layout and CSS styles, so it shouldn't be too hard.