Brainstorm some components that should be in this theme

[choldgraf]

In addition to the basic template structure, I think a few components could be useful to include as they will be really common across all themes. What would this list look like?

In my mind, there are two design cases that we could consider, and then figure out the most common patterns that would be repeated across all of them.

For a standard left-sidebar theme:

• A site-wide Table of Contents ({{ toctree(...) }} is sufficient for now)

For a top navbar theme

This theme has a top navbar with navigation and "more stuff in general" and a left-sidebar for an in-section navigation.

• A top-headers only Table of Contents
• A Table of Contents that starts at level 2 and otherwise behaves like {{ toctree(...) }}

Shared

• Display a logo (Initial round of component additions #14)
• Display the site name ({{ doctitle }} is sufficient)
• Display the in-page table of contents ({{toc}} is sufficient)
• Previous / next buttons (Add component: related-pages #15)
• Sphinx Ethical Ads HTML (Initial round of component additions #14)
• Breadcrumbs (Initial round of component additions #14)
• "Edit this page" (Initial round of component additions #14)
• Search bar HTML
• Hide highlights link/button, after search

A few fancier components (maybe delegated to themes?)

1. A list of FontAwesome icons + links for each button (basically, the pydata link behavior)
2. Text defined in config that becomes footer text (since most users probably don't want to have to write custom HTML templates in order to take advantage of the "footer" section)
3. Text defined in config that becomes announcement text (for the same reason)

Any thoughts on this?

[pradyunsg]

Breadcrumbs would be another thing.

[pradyunsg]

1. A list of FontAwesome icons + links for each button

I'm a strong -1 on adding a dependency/vendoring Font Awesome in this theme directly, but I'm on board for having something that needs the downstream theme to declare the config option, add font-awesome however it wants, and include the component somewhere on the page. :)

[choldgraf]

Added breadcrumbs and another item about 'ethical ads placement' + a version switcher. Is there a similar RTD template it looks for for the "hovering RTD button" placement?

re: FontAwesome, I think the more important thing is the specification rather than the implementation of specific icon packs. Maybe it'd just be a dictionary of link: CSS class mappings, that would render to HTML in such a way that it would work if FontAwesome was loaded?

[pradyunsg]

I'll actually break out the RTD things into a separate issue, so that we can have a back-and-forth with RTD folks on that! :)

[pradyunsg]

A site-wide Table of Contents (e.g., {{ toc }})

(I'm assuming you meant to say {{ toctree }} here)

Does this need to be a dedicated component, given that the only thing I can think the component file being is... {{ toctree }}? At best, it'd have a wrapper div/span. That feels like... unnecessary complexity?

Display the site name

Same as above, but with {{ docstitle }}.

Display the in-page table of contents

Same as above, but with {{ toc }}.

Previous / next buttons

This is tricky to make into a component, since there's lots of ways to do it. Should I just pick one of no-svg-or-asset-dependencies approach and use that here?

Search bar HTML

Same as above?

Version switcher dropdown

Let's track this in #12. :)

A few fancier components (maybe delegated to themes?)

I think I would delegate most of these to the themes, since it's basically going to be {{ theme_announcement }} or whatever, which is easy enough.

"Edit this page" / repository components that map onto source files

IMHO this is the only one of the fancy components, that genuinely benefits from being standardized across themes.

[choldgraf]

A few quick thoughts:

(I'm assuming you meant to say {{ toctree }} here)

Yes - but, one other thing we could consider adding is a {{ toctree }} that begins at the second level, and allows for captions. Basically, the stuff that's happening around pydata/pydata-sphinx-theme#346

This would be something any site needs if it wants to follow the "top-level navigation in the topbar, within-section navigation in the sidebar" pattern. So maybe common-enough to have upstream? WDYT?

This is tricky to make into a component, since there's lots of ways to do it. Should I just pick one of no-svg-or-asset-dependencies approach and use that here?

That seems like a reasonable start - just something that'll make the links properly exist and be put into an HTML blob, and others can figure out what to do with the HTML blob if they wished?

For all your other comments, yeah I generally agree. The trick will be figuring out what "non obvious standard components" are nonetheless so common that there's value in adding it. Perhaps the right approach is to begin with a minimal set, and then organically add only as there's clear demand

[humitos]

Previous / next buttons

This is tricky to make into a component, since there's lots of ways to do it. Should I just pick one of no-svg-or-asset-dependencies approach and use that here?

Whatever that way is, I'd suggest to show the name of the section you are accessing on those buttons as well. Just "Next" and "Previous" buttons are terrible to me. I love the ones that have both:

>> Next
Installation Guide

<< Previous
What are this docs?

I think it's way clearer where are you going if you click those buttons.

[pradyunsg]

I took the liberty of editing the issue description, into a checklist; crossing off the things that we seem to agree won't need dedicated components.

I've also added "hide this search", which is something that Sphinx's own documentation has but I haven't seen in too many other themes; and it's useful.

[mgeier]

Regarding "hide search highlighting", see also readthedocs/sphinx_rtd_theme#816 and readthedocs/sphinx_rtd_theme#876.

My own Sphinx theme has a quite prominent button (or rather link) for this: https://insipid-sphinx-theme.readthedocs.io/en/0.2.4/intro.html?highlight=topbar#features

[pradyunsg]

Ah yes!

Insipid was where I'd seen it for the first time! Thanks for chiming in @mgeier! :)

[pradyunsg]

I think 0.0.1.alpha3 is the first experimentally-usable release of this theme.

I've got the off-canvas sidebars working, things need accessibility labels, the more complicated components are still needed, and the documentation needs a lot more words; but the basic scaffolding and core concept of this project are set up now. Now for the long tail of rounding out the rough edges, and figuring out the fun bits! :)

[pradyunsg]

Also, the docs are up, and the changelog is at: https://sphinx-basic-ng.readthedocs.io/en/latest/changelog/

[pradyunsg]

With the most recent pushes, I've added all the non-navigational components. With that, I'm going to close this.

I'll create a separate issue to discuss and track adding navigational stuff!