Components for ReadTheDocs stuff

[pradyunsg]

A bit of context: this theme is basically an attempt to create a new base, for Sphinx themes to reduce the amount of duplicated effort in the ecosystem.

In #11, @choldgraf and I (for now, hopefully more folks will pitch in soon) are brainstorming what "reusable chunks of HTML" we should provide downstream theme authors, to make their lives easier. We're calling them components.

For reasons that I hope are obvious, it'd likely be a worthwhile investment to have this theme's components work well on RTD. This is basically an issue for having a place to discuss about how to make that happen! :)

/cc @humitos @stsewd @ericholscher

[pradyunsg]

Looking at https://github.com/readthedocs/readthedocs.org/tree/master/readthedocs/core/static-src/core/js/doc-embed, I can see what RTD's embed JS does. Here's a few notes + comments on potential changes that'll make it easier to get things working here:

• version-compare.js: Injects a warning admonition, on outdated docs.
  • This currently assumes that the page has a div.body and div.document while will almost certainly not be True for themes deriving from this one (or Furo FWIW).
  • Suggestion: Change this to look for a tag with role="main", since that's what Sphinx's search uses as well.
• sponsorship.js: Injects the ad.
  • This just works with the new and clean data-ea-publisher: https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/sidebar/ethical-ads.html
• sphinx.js: Handles the version selector tracking logic.
  • I can't figure out how it populates this. Likely with footer.js? :)
• footer.js: Can't figure out what this does.

[pradyunsg]

So, I guess... here's my questions for the RTD folks:

• Version selectors:
  • What does this JS need from an element in the page's DOM, to trigger embedding the RTD-version-selector's HTML in that element?
  • What does the embedded HTML look like? Is there a good way to test for this locally?
• Old version warning:
  • Could you start embedding the admonition to the [role=main] element, rather than in div.body div.document?

[ericholscher]

@pradyunsg I'd recommend you take a peek at readthedocs/readthedocs.org#8052 -- where we're doing a design doc on the future of the integration here to make this kind of thing easier.

[choldgraf]

@ericholscher ah very cool - given that this "base theme" will likely not become totally integrated with docs for a little while (I suspect a few weeks at the very earliest, @pradyunsg lemme know if I sound off there!), does it make sense to design for the new implementation of the ads integration and such?

[pradyunsg]

@ericholscher Thanks for that link! Any idea how long the v3 API would possibly take?

TBH, I'm actually willing to put in the time to figure out how to stylize /api/v2/footer_html's output (it shouldn't be that difficult) assuming someone either points me to how to get that OR I figure out how to "look like" RTD-Sphinx-Theme to the JS. :)

FWIW, I'm definitely on board for straight up upgrading this theme for v3, once that's available -- I think it' personally don't think we need all that though, just information about how stuff works right now w.r.t. the version selector/popup would be sufficient.

(I suspect a few weeks at the very earliest, @pradyunsg lemme know if I sound off there!)

If "few" means >= 2 weeks, yea. I'm hoping to cut a release over this weekend, and maybe switch Furo over to this over the next weekend. That's of course assuming that this (and a couple of pip things I've lined up for myself) won't take more than 2 weekends + 1 week's free-time-that-goes-towards-OSS. I'm also hoping to put together something that's like GitBook (with Furo's style language) that's built off of this as well. That's probably another 2 weeks. :)

[choldgraf]

Sounds good - I was also imagining similar (or longer) timelines.

I'm also hoping to put together something that's like GitBook (with Furo's style language) that's built off of this as well

Just a quick thought - why make another 3 column layout-style theme? Why not either turn that into the Sphinx Book Theme, or the PyData Sphinx Theme? (assuming both will wish to use this base theme component, and have very similar design goals to gitbook)

[pradyunsg]

Just a quick thought - why make another 3 column layout-style theme?

Hah. This is a great question! This sent me down a fun mental spiral and I needed to step away, pace up and down in my house to figure out why I wanted to do this.

[snip story I rambled on about, with too much information for a publicly visible message]

To put it simply: I've found the process of writing a theme fun, so I wanna write one with no strings attached. :)

---

Basically, I don't want to be doing the "difficult" bits right now; only the ones that are fun in my book and changing existing Sphinx themes just isn't one of them. Yes, the folks are great, but I'm probably not gonna find the actual work fun. And I'm obviously optimising for fun here. :)

Changing an existing theme has all of the things I do NOT want to be doing right now:

• Thinking about backwards compatibility concerns (because they have existing user bases).
• Dealing with change-management overhead of too-many-user-facing-knobs and users-depend-on-things-we-never-promised.
• Needing to discuss ideas and communicate around them, instead of just... doing them and navigating by feel.
• Expectation management with others and concensus building.

[stsewd]

Hi, answering some questions

What does the embedded HTML look like? Is there a good way to test for this locally?

footer.js calls this API https://docs.readthedocs.io/_/api/v2/footer_html/?project=docs&version=stable&page=index&theme=sphinx_rtd_theme&format=jsonp&docroot=%2Fdocs%2F&source_suffix=.rst which returns the content to be injected.

Could you start embedding the admonition to the [role=main] element, rather than in div.body div.document?

Yeah, but we would still need to fallback to the other selector and maybe also look for the main tag.

[pradyunsg]

Notes for future self:

• https://github.com/readthedocs/readthedocs.org/blob/c70c6e8edc97d1f8a0e8420c5456c3696bd72fb3/readthedocs/api/v2/templates/restapi/footer.html is the template that's rendered for HTML.
• https://github.com/readthedocs/readthedocs.org/blob/c70c6e8edc97d1f8a0e8420c5456c3696bd72fb3/readthedocs/api/v2/views/footer_views.py#L145 is the context for that render.
• https://sphinx-basic-ng.readthedocs.io/_/api/v2/footer_html/?callback=callback&project=sphinx-basic-ng&version=latest&page=index&theme=furo&format=jsonp&docroot=%2Fdocs%2F&source_suffix=.md is the call made by the RTD script, for the home page of these docs.

Yeah, but we would still need to fallback to the other selector and maybe also look for the main tag.

Not really? Every page is basically required to have [role=main], because Sphinx search depends on it. :)

[stsewd]

oh, sorry, I thought you meant other thing, this can be updated yeah https://github.com/readthedocs/readthedocs.org/blob/4b4ca8e3e2231b4219dc8ab8ac199eceff7e05cf/readthedocs/core/static-src/core/js/doc-embed/version-compare.js#L28-L31