executablebooks
Change package name
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 (https://github.com/executablebooks/sphinx-togglebutton/issues/11#issuecomment-625975239 and https://github.com/executablebooks/sphinx-panels/issues/14#issue-619124074) 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.
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)?
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/
(minor downside: people might think on first sight that it is related to "widgets" from the jupyter ecosystem)
Yeh good point; just a suggestion from #17 that I though was worth throwing into the mix
Strong +1 for calling it sphinx-components.
Meta question: How do we figure out the final decision/concensus here?
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."
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:
- Do a find/replace for
sphinx-panels -> sphinx-componentsandsphinx_panels -> sphinx_componentsin the package - Take a pass to make sure we didn't miss something (e.g.
Sphinx Panels) - Upload a new PyPI package for this
- Add a deprecation notice to the old PyPI package
- Do the same for the ReadTheDocs documentation
Anything else?
I'd start by reserving the PyPI name and RTD name, to avoid any pain around name retention policies.
@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?
@choldgraf renaming to sphinx-components is fine, but what about including in this new package sphinx-togglebutton as well?
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. :)
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). :)
Yeah at least in the short-term, I like the idea of explaining this package as "Sphinx directives to provide shortcuts to bootstrap components"
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".
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?
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)
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?
Well the main issue with bootstrap and sphinx is that pesky container class that sphinx adds to all container nodes
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 :shrug:
- Dropdowns (already implemented -- dropdowns)
- Forms (not relevant)
- Input group (not relevant)
- Jumbotron (not relevant -- mainly for themes?)
- List group :shrug:
- Media object :shrug:
- 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 :shrug:
- Toasts (not relevant?)
- Tooltips (not relevant?)
covered by rST's GUI labels
what are these out of interest, I don't recall coming across them?
Well the main issue with bootstrap and sphinx is that pesky
containerclass 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.
"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.
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.
This will essentially be closed by https://github.com/executablebooks/sphinx-design/issues/6