Discuss shared theme infrastructure between EBP and other themes

[choldgraf]

Background

Currently there are several themes that have slight variations on the same structure:

• PyData Sphinx Theme - Maintained by the PyData community, in particular myself and @jorisvandenbossche (ping also @bollwyvl)
  • Sphinx Book Theme - Maintained by the EBP community (in particular @choldgraf, @mmcky, @AakashGfude, and @chrisjsewell) and dependent on the PST
• Furo - Maintained by @pradyunsg
• QuantEcon Theme (demo here) - Maintained by the QuantEcon community (in particular @DrDrij)
• Inspid Sphinx Theme - maintained by @mgeier

A lot of these themes share the same basic structure - a topbar, left sidebar, middle content, right sidebar, and bottom nav/footer. They also share many similar UI elements (eg., "click to expand subsections" in the sidebar). As a result there is a lot of duplication of similar work and UI/UX happening across these themes.

Proposal

Can we open a discussion for opportunities to unify pieces and use shared infrastructure? For example, we could unify on a single basic theme that defines the "topbar + 3 column layout" structure that we all use. This would be minimalistic and unopinionated, and designed to be sub-classed and styled by other themes. It would have an HTML structure that was templatizable, customizable, and extendable. (it could be one of the pre-existing themes, or a new basic theme that we'd depend on).

One idea for this theme structure could be this proposal from @chrisjsewell for a sphinx-book-theme layout. Perhaps we could generalize this to provide the right foundation for all of these themes, and thus have a good starting foundation for each.

If enough folks were on board with this, there are a few ways that we could collaborate towards making it happen (in increasing order of complexity):

• Agree that this would be useful in theory, and then wait for somebody to try building it themselves
• Define some common pieces that we'd all want as a "spec", and then wait for somebody to try building it themselves
• Do the above + coordinate development time between the teams to make this happen
• Do the above + write up a small grant to pay for a part of somebody's time to make this happen
• Do the above + write a more complex grant like a CZI EOSS grant.

Things to include in a shared theme

General layout
Topbar, with 3-column layout beneath, w/ footer below. Basically this proposal from @chrisjsewell for a sphinx-book-theme layout

Here's a screenshot for reference:

Modular HTML components
Components as standalone HTML templates that can be placed in different spots in page with jinja includes

• Site logo
• Search bar
• In-page TOC
• Across-page TOC (configurable to start at level 2 or level 1)
• Icon links
• Links to edit page / go to repo / open issue
• Breadcrumbs

Things to do

• Decide whether this is a good idea to pursue for all of our respective projects
• Agree on a rough spec that would be the right balance of extensible + feature-rich that would be most useful
• Scope out how much work it would take to build a theme from scratch and wrangle the sub-projects to guide its development.
• Decide if or how we'd like to fund that work
  • E.g., a NumFocus grant O($20,000)
  • Or a bigger grant like a CZI EOSS grant

Questions

• Do others agree that it is useful to try and unify some of our theme infrastructure?
• If so, I would love to hear others' thoughts about how we could go about doing this to minimize work and maximize impact.

[pradyunsg]

Agree that this would be useful in theory

I agree!

a new basic theme that we'd depend on

This is what I think would be best, ideally without depending on Bootstrap or anything else (Furo demonstrates that this is not just possible, but also achievable). 🙈

This would be minimalistic and unopinionated, and designed to be sub-classed and styled by other themes.

One question I have here: do we want this to be like Sphinx's basic theme, where it only provides the assets + bare-bones styling, or do we want the styling to be a bit more fleshed out and usable (but overriddable)?

One option is to split the CSS for this theme into 2 parts: "scaffold.css" and "theme.css", where the "theme.css" can be what derivatives override/provide, while the scaffold is in the base theme! :)

[choldgraf]

Good point about the bootstrap - I think that kind of question is also important to ask: would a shared project need to be done without any JS/CSS framework? Or would something like Bootstrap be on the table of options? To me the benefit of bootstrap is that it lets people who aren't web developers make quick progress. OTOH if the base theme itself is designed well enough, perhaps this is not necessary? I'd be curious if @DrDrij has any experience there.

[pradyunsg]

I spent some more time thinking about this, and I feel like it'd be good to add a few more "components" to this base theme, even if they're not included by default:

• "breadcrumbs": I quite like how Just The Docs does this and it'd be nice to have something in the base theme to generate the "skeleton" for this.
• Announcements on top: Furo has this. So does mkdocs-material. So does Django's documentation. So does PyPI.org when there's something useful to say -- it's a site-wide, top-of-page thing: https://pradyunsg.me/furo/customisation/#announcement

[choldgraf]

Announcements is a cool idea - you don't think that's something that could be done via an extension so it's theme agnostic? Eg you could add a node above the title node in the doctree of each page or something.

I started collecting a list of shared features that seem broadly useful across all themes in the top comment

[jstac]

Given the biomedical focus, a CZI EOSS grant might tie in well with the shift of @gregcaporaso's team's QIIME material to JB. That work is partly in scope of existing commitments but perhaps development of common theme infrastructure could take place concurrently with development of a theme specific to their publications --- analogous to QE's theme mentioned above.

[pradyunsg]

Announcements is a cool idea - you don't think that's something that could be done via an extension so it's theme agnostic?

Nope, I don't think this can be theme agnostic.

The announcement is supposed to be above the top bar, which is really not possible to do unless you know what the skeleton of the theme is -- which makes it theme specific.

[chrisjsewell]

One idea for this theme structure could be this proposal from @chrisjsewell for a sphinx-book-theme layout.

ah yeh cool, I was just about to moan that I had already proposed this lol.

would a shared project need to be done without any JS/CSS framework? Or would something like Bootstrap be on the table of options? To me the benefit of bootstrap is that it lets people who aren't web developers make quick progress.

Probably no, we should not depend on Bootstrap, at least not how we do now.
For example, to have the left side-bar appear from the left (not top) as we very definitely should, the pydata/sbt theme template has to be completely re-done, not using bootstrap's grid framework.
Also, there is the issue with the incompatible sphinx and Bootstrap container CSS classes

[gregcaporaso]

Given the biomedical focus, a CZI EOSS grant might tie in well with the shift of @gregcaporaso's team's QIIME material to JB.

@jstac, I'd be happy to do whatever I can to support this. I am planning an unrelated EOSS round 4 proposal so I'm not sure if it would be a detriment to this one if I were to serve as a co-investigator on another one. I also probably wouldn't need to be a co-investigator to support the project though - like you mentioned, this work could be considered in-scope for the Sloan award.

[jorisvandenbossche]

Thanks Chris for starting this conversation! I also fully agree that it would be nice to have a closer collaboration and shared foundations.

Regarding bootstrap, the main reason that we use it is because when I started the pydata-sphinx-theme (then pandas-sphinx-theme), that seemed the easiest way to get something working relatively quickly for somebody with no web dev experience like me ;)
I still think that was a valid choice, but I assume that once a theme has been developed and is working without bootstrap (like @pradyunsg has done with Furo), it shouldn't be harder to maintain and further develop it (the value of bootstrap is probably mainly in the bootstrapping phase .. ;-)). So if there would be an effort (funding) to rebase pydata-sphinx-theme/sphinx-book-theme on something without bootstrap, I think that would be fine for me.

(and it's true that there are regularly compatibility issues with bootstrap's styling and sphinx / docutils output)

[jorisvandenbossche]

This [basic theme] would be minimalistic and unopinionated, and designed to be sub-classed and styled by other themes.

One aspect that's not fully clear to me is whether this would actually be "minimalistic". Would it rather be the superset of the different themes, or the common subset of the features of the different themes?

Concrete example: for pydata-sphinx-theme, the navbar with navigation is quite essential. But the other themes don't use that.

[choldgraf]

I've added a screenshot of @chrisjsewell's layout proposal above so it's easier to reference. @jorisvandenbossche I think one approach is that we could treat the PST navbar items like any other template. The theme could have configuration that would add templates to these sections.

So for the pydata theme it could be something like:

theme_topleft_templates: ["logo.html", "navbar_top.html", ...]
theme_topright_templates: ["social_buttons.html", ...]
theme_sidebar_templates: ["navbar_inpage.html"]

and for the Sphinx Book Theme it could be:

theme_topleft_templates: []
theme_topright_templates: ["social_buttons.html", "launch_buttons.html", ...]
theme_sidebar_templates: ["logo.html", "search.html", "navbar_inpage.html"]

something like that

[pradyunsg]

So... since @choldgraf posted this here, I've started scaffolding the project and HTML for this, to figure out what this should look like. (I'll make the repository public sometime next week, because right now everything is super rough and unsettled so taking direct inputs on the code won't be particularly useful for anyone).

At this point, I'm probably halfway through the whole discovery process for this, and I'll probably treat the rest of this discussion as a "collect everyone's inputs and try to build something that accounts for all of them".

Agree that this would be useful in theory, and then wait for somebody to try building it themselves

In other words, I got nerd sniped and this might be what we're doing now. Minus the "long wait" implied. 🙈

---

Oh, and I have a few fun questions for everyone here:

(my thoughts are in the nested bullet because... I'm on mobile in bed, and don't have a second editor to cut-paste them into a separate comment)

• Do we want this to depend on the basic theme?

  • If not, we could write our own searchtools.js and internationalisation (which are the only things that the basic theme's JS provides).
  • I think we should depend on basic, but it would be super cool if we could make it possible for the end user to use different search engines via plugins. (internationalisation should definitely stay by default tho, and leverage Sphinx's existing mechanisms)

• Can we enforce HTML 5 in this?

  • I really want to, but does anyone here want to support really old browsers?

• The basic theme in Sphinx has a "changes" directory, which depends on ancient HTML things (frameset) that are deprecated. Those files are used by sphinx's changes builder (which I didn't know existed). What do we want to do about this?

  • I've currently put down the warn("This is not supported yet. TODO: Figure out whether we want to support this.") for those pages. I'm inclined to just remove the TODO and make this something that the scaffolding doesn't provide. That way theme authors will have to decide (on a theme-by-theme basis) how they wanna handle this, since they can override the template.

• How do we want to handle sidebar elements, given that we'd have 2 sidebars and only 1 html_sidebars in the configuration?

  • Don't do anything for this in the scaffolding theme. The scaffolding theme shouldn't provide any HTML for the sidebar content, nor any styling beyond that barebones scaffolding.

• Should the theme provide sections for html_sidebars by default (especially if it's inheriting from basic)?

  • No? The theme is currently replacing all the sidebar elements with warn("whatever.html is not supported by this theme") with the hope being that downstream themes will override these templates. This is because (1) making downstream themes opt-in to the weirdness that is the Sphinx sidebar situation and (2) allowing users porting over from other themes to notice that their sidebar declarations are incorrect (because of the warning) if the theme doesn't support them.

• Should this theme handle the margin based content styling and collapse logic?

  • I feel not-by-default, in the same spirit of having themes opt into these things. Additionally, the margin content requires additional CSS and custom not-in-Sphinx-by-default directives so I can make a case for why not all themes would want that. OTOH, it'd definitely be a good idea to have something reusable for this! I'm torn. :)

The theme could have configuration that would add templates to these sections.

I'm using theme templates/blocks-in-templates that can be overridden, since it won't expose this mechanism to the end user unless the theme opts-in to do so. (edit: I mean, the scaffolding shouldn't add user-facing theme options)

FWIW, my opinion on this is that the base theme should only provide the scaffolding and CSS for that scaffolding, and it should only provide theme-author-facing knobs. Let the theme authors control all of the user-facing knobs. OTOH, these knobs should 100% still be configurable for the theme authors (via the templates and setting Jinja2 variables, is what I can come up with). This isn’t set in stone though, because I don’t know what everyone else thinks. ;)

(PS: Furo intentionally doesn't have too many user-facing knobs, and I'd like to be able to switch over to this for it!)

---

Also, I've got a "theme-debug.css" file, which is what I'm using for debugging how the elements work (eg: for sidebar hover and shitz), but the default style would only be the scaffolding parts - with everything like fonts, typography, colors etc being the responsibility/stylised by the theme authors.

Also, perhaps the most bikeshedding bit: naming! (🌈) I'm thinking sphinx-basic-ng (as in next-gen) but am super open to bikeshedding this. Just, if you want to suggest names, you should probably also answer at least 3 of the questions above. 🙃

[pradyunsg]

Would it rather be the superset of the different themes, or the common subset of the features of the different themes?

My understanding was it'd be a subset.

Making it a superset means that bugfixes related to those parts would be tricky (similar to how SBT needs to wait for a pydata-sphinx-theme release to then make a bugfix release bumping the minimum version). I'm wary of it being a superset also because then it'll become a maintenance nightmare, due to the potential combinations that each of the design choices.

We could still have bits that we all agree are "easy to get wrong, difficult to get right", to make sure that we don't end up making the same mistakes.

[pradyunsg]

Yet-another question is: do we want the content and sidebar widths to exposed as customisable to the various themes?

It's significant complexity to allow this to be customisable, and I don't see any way to make this possible for theme authors without also exposing this to the end users as well.

I feel very strongly about not providing this knob to end users though, because there will be the occasional maintainer who'll want to have their documentation to have 100% width on wide screens, to the determent of all their documentation consumers.

But then again, I do want to hear what everyone else has to say. :)

[choldgraf]

That is a lotta text @pradyunsg :-)

• Do we want this to depend on the basic theme?

  • I don't have strong opinions. Most important is that we don't lose anything really useful/important in the basic theme. Though the more we create ourselves, the more we'll have to maintain.
  • The idea of making it easy to plug in a new search (e.g., to use lunr.js) is very cool.

• Can we enforce HTML 5 in this?

  • I think this is totally fine.

• The basic theme in Sphinx has a "changes" directory

  • No idea what this does but will defer to @chrisjsewell / @mmcky / @AakashGfude / others if they have opinions.

• How do we want to handle sidebar elements

  • Can we just define an html_sidebars_2 config?

• Don't do anything for this in the scaffolding theme.

  • I think the scaffolding theme could also provide a lot of useful components that behave relatively independently and could be placed in various spots as sub-themes wish. E.g., "top-level navigation", "full site navigation w/ dropdown buttons", "version selector", "social buttons", etc.

• Should the theme provide sections for html_sidebars by default

  • I think so - it should choose a minimal set that is not opinionated and reasonable.

• Should this theme handle the margin based content styling and collapse logic?

  • I'm not sure what this means - do you mean being "mobile responsive"? If so I think yes it should. Basically imagine anything that all of these sub-themes do. If they all do it, more or less the same, then it should be in the parent theme.

• it should only provide theme-author-facing knobs. Let the theme authors control all of the user-facing knobs.

  • That sounds correct to an approximation, though there should be a lot of documentation for theme authors in this case. Maybe start off w/o lots of options in the base theme, and then add them bit by bit as people wish?

• naming

  • What's the name for that standard "three column"+topbar layout? We can just call it that?

• widths

  • Maybe don't make it a knob but choose CSS classes so that it's relatively easy for people to tweak this + document it?

• public/private

  • I think it'd be helpful to have this discussion in a public repository relatively quickly, because answering this gigantic list of questions will be very cumbersome in a single issue...

[bollwyvl]

Late to the party, and haven't had time to fully grok this, but a huge win here (and good sugar for grantwriting) is not only going to "strict" HTML5 (whatever that means, but we can fully test it automatically), but further maximizing use of the HTML5 semantic elements which support readers using assistive technologies. Bootstrap 4, 5, 3000, whatever, no horse in the race, but having really a solid, positive accessibility stance is really good for everyone, including the search engines that help us find stuff.

So, concretely:

• less div/span soup, but more intentional main / article* / section*, structure
• use figure and figcaption, etc.
• where div and span, etc. are unavoidable, include the appropriate role tags.
• aria-label, aria-selected, etc.
• keep a non-trivial site under continuous assessment with pa11y-ci, as on this pr

We're looking to do some of these things in other places in the pydata ecosystem, such as JupyterLab and an attendant nbconvert theme (e.g. labhtml5), but docs are great place to start.

🛎️ @isabela-pf @tonyfast (can y'all reach out to the numpy folk we were chatting with the other week?)

[choldgraf]

@bollwyvl great point that accessibility and semantics are also important "out of the box defaults" to have in a base theme. I think that would be a very compelling funding case for CZI.

[bollwyvl]

and semantics

To be sure, I'm not talking "Big S" semantic (e.g. RDFa or JSON-LD), much as I would love to see those promoted: just using broadly-supported HTML5 elements that have well-defined structural meanings, when possible.

[pradyunsg]

less div/span soup, but more intentional main / article* / section*, structure

I tried doing this with Furo, and this is certainly do-able.

The missing bits are things that are generated by Sphinx (it puts out <div id="..." class="section"> for example). That also applies to with figure and figcaption. I don't think the theme should be the one fixing this, and this should be fixed upstream.

That said, if we're willing to be hacky, we can definitely parse and rewrite the output from Sphinx. :)

---

One of the thing I'm noticing while writing this is that the themes might want to make fairly different choices around the "skeleton" of the various things:

• responsive breakpoints
• whether the page-toc sidebar supports margin-content
• whether the "left" sidebar is stuck to the edge of the page (like https://docs.docker.com/develop/ and https://doc.rust-lang.org/cargo/) or aligned to the center with the content (like https://pradyunsg.me/furo/ and https://squidfunk.github.io/mkdocs-material/getting-started/).

For now I'm just going to make a single choice on these, but I'll file issues for each of them once I get the public git repository online. There's still the open question on how to share the SASS / SCSS across themes, but we'll get to that later. :)

[pradyunsg]

Alrighty! https://github.com/pradyunsg/sphinx-basic-ng/ is up and public.

I've got the basic responsive breakpoints settled down I think, and the barebones skeleton is working.

Screen.Recording.2021-03-14.at.6.33.32.PM.mov

There's 2 "big skeleton" things missing:

• all the menus-being-accessible-with-buttons part.
• left sidebar covering the left-portion of the page, like Furo / GitBook / JustTheDocs.

One thing I'll note is that, well, the colors make the differences between the various layouts more obvious, but some of the breakpoint changes will look much less prominent once we remove these debugging colors. :)

PS: I notice now that I should've probably added a background for the "next/prev buttons". :)

[pradyunsg]

Oh, and if you want to try it out from a git clone of the repository, install [nox][https://nox.readthedocs.io/] with pip in a virtual environment and run:

nox -s docs-live -- ./tests/barebones/

[choldgraf]

Nice! Thanks for sharing - a couple quick thoughts:'

• I think the header should be split into left_header and right_header template sections. That way one could recreate the pydata sphinx theme structure of "logo + nav bar on the left" and "social buttons etc on the right" (or other similar layouts)
• I think each section should have a list of templates associated with it, similar to html_sidebar. Then in the base theme, it would iterate through that list and insert templates. Does that make sense?
• The next question is then "what templates live in this base theme, vs. being in a child theme? Did you have an idea for this one already?

[chrisjsewell]

Nice one cheers! yeh I will try to give it a test run in the next few days.
I would jump in there now and say, will you consider (or were you already) to move this to https://github.com/executablebooks/ at some point, so that all the participants here can be maintainers 😬

I think each section should have a list of templates associated with it, similar to html_sidebar. Then in the base theme, it would iterate through that list and insert templates. Does that make sense?

Yes this is definitely what I had in mind in my proposal, although obviously it depends how this works in practice.

The next question is then "what templates live in this base theme, vs. being in a child theme? Did you have an idea for this one already?

Indeed, we should start making a demo child theme sooner rather than later, to understand how this will work

Then obviously we should make sure we are implementing all the things we have learnt from building the current themes (looking through the open/closed issues/PRs), a few things off the top of my head that may or may not apply to the skeleton or just the children:

• Obviously I'm sure you were planning to get round to this 😄, but we should make sure that from day one there is very clear/complete documentation on the structure of the theme and the design decisions that went in to it.

• CSS/SCSS: The files that end up on the "live" documentation, definitely need to be hashed or otherwise named (adding version suffix?) such that changes in new versions are not "suppressed" due to browser caching. We had numerous issues about this open on jupyter-book before I implemented: executablebooks/sphinx-book-theme@ef8815f

• Translations: I did a lot of work on this in executablebooks/sphinx-book-theme@d2a8b44. I see you have used the _ function for a number of texts 👍 (e.g. _('Index')) but note that only work for texts available in the internal sphinx catalog

[chrisjsewell]

Oh and I also want to cc in to this discussion @mgeier who (as I mention in my original proposal) has been working on https://insipid-sphinx-theme.readthedocs.io

[choldgraf]

I just opened up pradyunsg/sphinx-basic-ng#7 with some more thoughts on the "components" idea, maybe we can iterate on thoughts there?

And thanks for pinging @mgeier - my bad I totally should have pinged you at the outset! I've added insipid to the top comment list as well 👍

[choldgraf]

I have a PR that implements some of the "component" ideas that I had - would love feedback from folks:

pradyunsg/sphinx-basic-ng#8

We can either keep iterating on that PR to change/add/remove what folks wish, or just use it as inspiration and iterate in other PRs, I will not be offended either way 🙃.

[pradyunsg]

will you consider (or were you already) to move this to https://github.com/executablebooks/ at some point

Yup yup. Let's do this once we've settled down on the issue tracker discussions though.

I'd actually tried creating the repository on executablebooks, before realising that I'm not even in the organisation. That also made it easier for me to decide where to put this right now (because I was split on that from a "how should we structure the initial collaboration effort for designing this" perspective).

I've found that when there's a bunch of folks (with each bringing their own opinions and preferences) collaborating on a single thing with GitHub as the primary communication channel, it helps (communication-wise) to not spread out the merge permissions in the initial design process and to have a single person be accountable for making sure that everything that someone said is accounted for.

I guess I've basically unilaterally decided to be responsible for making design choices while considering all the opinions/inputs here. Although if folks would rather we spread this responsibility out or have someone else be responsible for this, just say so. :)

what templates live in this base theme, vs. being in a child theme? Did you have an idea for this one already?

Yessss.

I'm hoping to make this look super barebones but still have all the structural bits in place (like the basic sphinx theme) and provide a bunch of components to use in downstream themes. Basically, no one would want to use this as-is (because it'd generate stupidly empty pages), but it would have all the HTML and CSS to make things usable should someone (like a theme author) decide to add bits of HTML and CSS and... et viola, it all works and looks pretty.

---

To elaborate a bit on what I had in mind when structuring this:

• The overall page "skeleton" positions the various "components" (eg: sidebars, content, header, footer etc) and those components contain the "elements" (eg: search box, toc etc).
• This theme provides a responsive skeleton structure, some components to place in various parts of the page, a bit of CSS for aligning things in that skeleton and some of the components.
• Derivative themes (that don't want to customise the skeleton structure) would only need to:
  • override elements/*.html files and populate those with a bunch of {% include "components/[element]/[thing].html" %}, possibly with a bit of wrapper HTML.
  • export some html_context variables for use by some of the elements. There will be helper functions to compute those values as necessary.
• Derivative themes that do want to customise these things that deeply, can override various blocks in page.html, and selectively use the default classes from the skeleton. This allows them to change the bits of the skeleton that they want to, while still using the other things that are provided by this theme.
  • This would allow for things like stuck-to-the-left sidebars like Cargo's documentation.

I think the header should be split into left_header and right_header template sections.

Actually, I had a bit of a different idea for this:

• If there's 2 tags (i.e. elements) in the header component, they would be left-right aligned.
• If there's 3 elements in the header component, they would be left-center-right aligned.

This is much easier to maintain upstream thanks to fewer points to interact with downstream themes and it is easier to adapt for RTL languages as well.

RTL support is also why I don't want to add "left" / "right" phrasing in various places overall, but instead alternatives like "primary" / "secondary".

I think each section should have a list of templates associated with it, similar to html_sidebar. Then in the base theme, it would iterate through that list and insert templates. Does that make sense?

It does make a lot of sense. I definitely want to make it easier for downstream themes to do this though, since it is a super nice way to allow extensibility for the end user.

I'm pretty much a strong -1 for doing it by default though, because that forces any/all derivative theme to provide those knobs because you can't remove a parent theme's theme_options. (yes, this is partly because I don't want to be providing any such knobs in Furo and [as yet unnamed and unreleased theme that I pulled this skeleton out of])

I think a Jinja macro, a helper function and good documentation should be enough to make this straightforward for downstream themes to do.

To generalise what I'm trying to say here: if it's touching theme_options, it should be something that the downstream themes opt-in to. We can make some of these things easier to do downstream (especially if it's tricky to get right or used in multiple places), but they should still be opt-in IMO.

very clear/complete documentation

Yup yup. Definitely want to do this. :)

CSS/SCSS

Let's talk about this in pradyunsg/sphinx-basic-ng#3.

Translations

100%. I actually also want to work on RTL support in this, because that's definitely one of those things that's really tricky to do.

I don't think we're at a point where we can talk much about this yet TBH, but hey, this is definitely on the radar.

I have a PR that implements some of the "component" ideas that I had - would love feedback from folks:

I've left some feedback (basically saying "I don't want to use theme_options, and please elaborate on why the current approach is insufficient for this"), but I've elaborated a lot more here on why that idea doesn't fit how I was modelling this in my head. :)

Let's continue the discussion on that issue tracker though, likely in pradyunsg/sphinx-basic-ng#2.

we should start making a demo child theme sooner rather than later, to understand how this will work

Yup, yup. The way I was thinking of doing this was to create a bunch of sample documentation sections in the tests/ directory that do all the things that we might want to (barebones does nothing, we'd have something that does roughly what SBT does, one for Furo, etc).

And then we can add proper tests for those (once we've settled on the overall approach/design).

And, it helps that I took this out of a half-done skeleton that was basically "Furo's cousin, for documentation that doesn't fit well in a single sidebar".

[choldgraf]

A few thoughts below..

before realising that I'm not even in the organisation LOL

Maybe we should create an @executablebooks/theme team for this organization, and add folks that are interested to it? We do not have a principled process for adding new people to the EBP members list, what responsibilities come with it, etc. Perhaps starting off with this team will be a step in that direction.

Although if folks would rather we spread this responsibility out or have someone else be responsible for this, just say so.

I'm fine with the current approach - the most important thing is that everybody's perspective is considered and given fair weight 👍 agreed that it is more efficient to have one or few people making decisions initially, so long as the feedback process is also given strong attention.

positions the various "components" (eg: sidebars, content, header, footer etc) and those components contain the "elements"

In my mind, component is a much more specific thing than a general section of the page (I think component and element are roughly equal in my mind). I think this is because of web-components which tend to be scoped to a similar complexity on the page.

because you can't remove a parent theme's theme_options

I'm gonna take discussion of this over to pradyunsg/sphinx-basic-ng#7

making a demo child theme sooner rather than later,

I think there should be at least 2 design cases here:

1. Furo/Book theme - left sidebar w/ navigation, content is rest of screen to right
2. PyData theme - topbar has more complex elements (left + right elements for example), similar furo/book theme structure beneath

I think it'll be hard to learn where the design choices are clunky until we try to recreate the current themes with this foundation.

[choldgraf]

If there's 2 tags (i.e. elements) in the header component, they would be left-right aligned

Do you think you could bring that discussion to pradyunsg/sphinx-basic-ng#6 ? It is really hard for me to follow all of these nested topic discussions in a single github issue 😬