Change package name

[chrisjsewell]

The package now has panels, link-button and dropdown directives, so perhaps the name should reflect this larger scope.
The name sphinx-bootstrap has been mentioned (executablebooks/sphinx-togglebutton#11 (comment) and #14 (comment)) but it's not particularly descriptive.

Another name that comes to mind is something like pydata-sphinx-extensions, since its genesis was from the components used in the pandas docs, using the pydata-sphinx-theme.

[chrisjsewell]

Maybe sphinx-layout

[jorisvandenbossche]

The sphinx-bootstrap is descriptive regarding how it is implemented, but indeed not really about what it does ..

But I think pydata-sphinx-extensions is just as not-very-descriptive as sphinx-bootstrap, personally (and the idea is also that people can use it with a different theme).

sphinx-layout might then be confusing that it is about the actual "layout" of the full page (cfr layout.html in theming)?

[jorisvandenbossche]

In the end, maybe the original sphinx-panels is not that bad. Also the dropdowns are kind of "panels" (the button a bit less so ..). It might depend on what other components might be added in the future.

Other idea: sphinx-components. I think all the elements that are used from bootstrap are things they call put under "components" in their docs: https://getbootstrap.com/docs/4.0/components/

[chrisjsewell]

New option: sphinx-widgets

[jorisvandenbossche]

(minor downside: people might think on first sight that it is related to "widgets" from the jupyter ecosystem)

[chrisjsewell]

Yeh good point; just a suggestion from #17 that I though was worth throwing into the mix

[pradyunsg]

Strong +1 for calling it sphinx-components.

Meta question: How do we figure out the final decision/concensus here?

[choldgraf]

Reviving this conversation as this package also now has tabs in it. I like sphinx-components, with one potential drawback which is that people might think we are referring to webcomponents. That said, I think components is a general enough name that this is probably fine.

I'm +1 on updating this sooner than later, and rebranding this extension to something like "A collection of lightweight bootstrap-based UI components for Sphinx."

[choldgraf]

It seems that we are converged on sphinx-components, yes? @jorisvandenbossche suggested and we have 👍 from @chrisjsewell , @pradyunsg , and myself. Do people agree? If so, I think the steps to take are:

1. Do a find/replace for sphinx-panels -> sphinx-components and sphinx_panels -> sphinx_components in the package
2. Take a pass to make sure we didn't miss something (e.g. Sphinx Panels)
3. Upload a new PyPI package for this
4. Add a deprecation notice to the old PyPI package
5. Do the same for the ReadTheDocs documentation

Anything else?

[pradyunsg]

I'd start by reserving the PyPI name and RTD name, to avoid any pain around name retention policies.

[choldgraf]

@pradyunsg I'm not sure how to reserve names on either PyPI or RTD - doesn't a project need to exist already in order to get the name?

[stefanodavid]

@choldgraf renaming to sphinx-components is fine, but what about including in this new package sphinx-togglebutton as well?

[pradyunsg]

Given that this package includes the bootstrap CSS by default (which can interfere w/ other Sphinx elements + theme styling for non-bootstrap themes), I'm inclined to suggest that we avoid adding more things here. :)

[pradyunsg]

doesn't a project need to exist already in order to get the name?

Yea. "reserving" to me is basically creating a barebones skeleton and upload it as a 0.1.0.dev0 (or similarly "low" version). :)

[choldgraf]

Yeah at least in the short-term, I like the idea of explaining this package as "Sphinx directives to provide shortcuts to bootstrap components"

[chrisjsewell]

The only component intrinsically linked to bootstrap components is the panels themselves, so I don't know if that description is accurate.

In fact, thinking off the top of my head, I'm inclined to perhaps consider, (a) have a look if the dropdown CSS can be separated from bootstrap, (b) consider not actually moving this package to sphinx-components, but instead creating a separate sphinx-components and moving every thing that is not the panels to that. This would make that package more "lightweight".

[choldgraf]

hmm - are you suggesting that sphinx-components should not have a dependence on bootstrap CSS, and would instead be a way to implement component-like things via custom CSS or JS?

[chrisjsewell]

are you suggesting that sphinx-components should not have a dependence on bootstrap CSS

Yes. The more minimal the CSS the better

and would instead be a way to implement component-like things via custom CSS or JS

well I would still put a high emphasis on CSS over JS, but perhaps relax the no JS rule to very minimal JS (to e.g. implement tab groups or other highly requested features)

[choldgraf]

yep makes sense

I think the question then becomes "how much developer energy is there for a non-bootstrap-based components project?" To me, the benefit of using bootstrap components is that it minimizes the amount of dev work to build a new directive that utilizes those components. What I worry is that if a separate sphinx-components package were created, there would not be enough developer time behind it to make a whole different package worthwhile. Does that make sense?

[chrisjsewell]

Well the main issue with bootstrap and sphinx is that pesky container class that sphinx adds to all container nodes

[pradyunsg]

Well, what all do we want to provide? Looking at the bootstrap component list, we have:

• Alerts (basically admonitions)
• Badge (covered by rST's GUI labels + already implemented here)
• Breadcrumb (not relevant -- mainly for themes?)
• Buttons (already implemented -- buttons)
• Button group (already implemented -- buttons)
• Card (already implemented -- panels)
• Carousel (not relevant)
• Collapse 🤷
• Dropdowns (already implemented -- dropdowns)
• Forms (not relevant)
• Input group (not relevant)
• Jumbotron (not relevant -- mainly for themes?)
• List group 🤷
• Media object 🤷
• Modal (not relevant?)
• Navs (not relevant -- mainly for themes?)
• Navbar (not relevant -- mainly for themes?)
• Pagination (not relevant -- mainly for themes?)
• Popovers (not relevant?)
• Progress (not relevant?)
• Scrollspy (not relevant -- mainly for themes?)
• Spinners 🤷
• Toasts (not relevant?)
• Tooltips (not relevant?)

[chrisjsewell]

covered by rST's GUI labels

what are these out of interest, I don't recall coming across them?

[pradyunsg]

Well the main issue with bootstrap and sphinx is that pesky container class that sphinx adds to all container nodes

This specific issue can be worked around with a bit of CSS -- https://github.com/pradyunsg/furo/blob/4164cc0625add44cdfd45fff44b49d5af661a301/src/furo/assets/styles/extensions/_sphinx-panels.sass#L5. The other issue is that Bootstrap stylizes everything in a "bootstrappy way", which can mess with themes not written with Bootstrap compatibility in mind.

[choldgraf]

what does the "role=main" thing do @pradyunsg ? I haven't seen it before

[pradyunsg]

"role=main"

It selects any elements on the page that are like: <tagname role="main">. Within any decent Sphinx theme, that's the element containing the "authored contents" of the page.

It's basically a consequence of Sphinx's search depending on this attribute (https://github.com/sphinx-doc/sphinx/blob/7eabbfc5ecdf52329672410f651880645074e215/sphinx/themes/basic/static/searchtools.js#L65), and is fairly reliable for Sphinx documentation TBH.

[pradyunsg]

what are these out of interest, I don't recall coming across them?

I recently came across them on https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/demo.html#inline-markup (see the paragraph starting with "GUI labels"). They're not strictly an equivalent replacement, but they're close enough for the simple cases.

[chrisjsewell]

This will essentially be closed by executablebooks/sphinx-design#6