Compare to pandas accordian

[chrisjsewell]

I quite like the accordion toggle in https://pandas.pydata.org/docs/getting_started/index.html#intro-to-pandas, and we are thinking of doing something similar in the AiiDA documentation.
They actually achieve this by using lots of raw HTML (https://github.com/pandas-dev/pandas/blob/master/doc/source/getting_started/index.rst), which isn't ideal, and I feel this might be handled by this package.

Aslo linking the minimal accordian tutorial: https://www.w3schools.com/howto/howto_js_accordion.asp

1. One of the initial things that is "better" with their setup is that there is no space below the title, when collapsed.
2. For this use case it might also be nice to have the option to have the button to the right of the text

[choldgraf]

Nice - I quite like the accordions. I guess they piggy-back on bootstrap for this kinda thing (https://getbootstrap.com/docs/4.3/components/collapse/) but if we want the toggle button to be theme-independent then that might not be possible. Maybe we could add a check for bootstrap, or a flag or something?

[chrisjsewell]

I went ahead and made a version of it in https://github.com/chrisjsewell/aiida_core/blob/docs-revamp-intro-install/docs/source/_extensions/accordion.py 😄 Yeh they were directly using some of the CSS from the bootstrap.min.css, which I distilled into the CSS I've used, and borrowed some of the JS from here 😁

You may have noticed I've also just created https://github.com/executablebooks/sphinx-panels. This is an idea from pandas as well and is quite nice for documentation, e.g.

[choldgraf]

I saw that! I think it looks great...maybe we can have a brainstorm about what are the "common visual elements" seen across books that it would be worth making into directives.

Another one I like from the pandas docs is this structure of a question:

That also seems like it could be a part of the "toggle button" approach.

I'm definitely not strictly tied to our current "little grey button to the right" approach if we can find something that is more sensible in the CSS. I think I am also fine depending on bootstrap for more advanced features, and telling users that they need to load bootstrap if they want advanced stuff to work. WDYT?

[choldgraf]

I just had a chat with @jorisvandenbossche, who is the lead on the new "pydata sphinx theme". It sounds like they're interested in doing many of the same things (directive-ifying things etc). For example, they have a PR to generate the "cards" you mentioned with container directives and classes: pandas-dev/pandas#32065

It would be great if we can coordinate a bit with the Pandas community on this so that we don't duplicate efforts in generalizing some of these visual elements.

[chrisjsewell]

Ah interesting cheers.
Yes they still use classes specific to bootstrap,
and my approach in sphinx-panels is to make it a bit more user-friendly, at least for more simple use-cases (not having to remember a tonne of classes and the exact ordering of containers etc). But happy to coordinate with them

[chrisjsewell]

I think I am also fine depending on bootstrap for more advanced features, and telling users that they need to load bootstrap if they want advanced stuff to work. WDYT?

For our use case with jupyter book yes, but for providing general use case directives it's not ideal. Currently, trying to coerce AiiDA to use bootstrap lol aiidateam/aiida-core#4029

[choldgraf]

if we can achieve the same effects without requiring full bootstrap to be loaded, then I am 💯 for it - just don't want to create a huge maintenance burden on us by being too generic. It's already something I've run into with sphinx-copybutton...that's a quite simple extension but there are many "this extension looks weird in <some theme I haven't used before>" issues

[chrisjsewell]

FYI a minor thing, but the buttons overlap the drop-down menu:

[choldgraf]

you mean I can't just put z-index: 999 on everything and solve all my problems? 😄

[chrisjsewell]

Yep, if you open a PR for pydata theme to have theirs at 1000 😆

[jorisvandenbossche]

@chrisjsewell sorry for the slow reply here. But, to be clear, I am all for better coordinating this / avoiding duplication! Cleaning those up in pandas (to avoid all this ugly raw html) has been a bit on the backburner, as you can see from the stalled PRs .. ;)

When we started doing this for the pandas docs, the idea has always been to eventually upstream it to the theme, as it looked like generally useful building blocks (but it was a bit easier at the time to just quickly hack together what we needed in pandas ;)).

Now, moving it to a separate package, instead of the pydata-sphinx-theme is fine for me as well (certainly if the capabilities start to grow, and mostly because people might want to use it without using the pydata-sphinx-theme).

So it seems you basically already implemented all of it in sphinx-panels? 😃
So then I suppose what would be most useful short term is that I try out sphinx-panels to see if it works for us for the pandas docs to replace our raw html hacks?

One thing I am wondering: I understand the desire to make it available for people not using a bootstrap-based theme otherwise, but doesn't that give a risk on incompatibilities between the parts of bootstrap css you included in the package vs the bootstrap your theme is already loading?

[jorisvandenbossche]

Sphinx-panels is cool! 😃

I quickly tried it out for one of the pandas pages. On top is with sphinx-panels, at the bottom our original raw html ones (can you spot the difference .. ?):

(and we need to fix the "bug" with the green area left/right of the code blocks in both cases ..)

And the rst I needed for this:

.. panels::
    :card: shadow install-card

    column += install-block

    Working with conda?
    ^^^^^^^^^^^^^^^^^^^

    pandas is part of the `Anaconda <https://docs.continuum.io/anaconda/>`__ distribution and can be
    installed with Anaconda or Miniconda:


    ++++++++++++++++++++++

    .. code-block:: bash

        conda install pandas

    ...
    column += install-block

    Prefer pip?
    ^^^^^^^^^^^

    pandas can be installed via pip from `PyPI <https://pypi.org/project/pandas>`__.


    ++++

    .. code-block:: bash

        conda install pandas

    ...
    column = col-12 install-block

    In-depth instructions?
    ^^^^^^^^^^^^^^^^^^^^^^

    Installing a specific version? Installing from source? Check the advanced installation page.

    .. container:: custom-button

        :ref:`Learn more <install>`

So for those cards, that seems to be working very nicely !!
(I add the install-card and install-block classes to use the existing css we had to style the cards)

Thanks a lot for turning our idea/hack into a nice package ;)

[jorisvandenbossche]

One thing I am wondering: I understand the desire to make it available for people not using a bootstrap-based theme otherwise, but doesn't that give a risk on incompatibilities between the parts of bootstrap css you included in the package vs the bootstrap your theme is already loading?

Reading the docs now, this seems already be handled with panels_add_boostrap_css = False, perfect!

I have some more questions about the panels, but will open an issue on the sphinx-panel repo, instead of hijacking this thread about it.

---

So that was about the panels/cards, but the original issue here was about the "accordion". What are your current thoughts about that?
It could also something to be added to sphinx-panels ? (the way we currently do it in pandas is also with cards)

The other elements we currently have in pandas:

• The "custom-button" container: this is actually just some css
• The "question" div, the callout, etc on the actual tutorial pages (eg https://pandas.pydata.org/docs/getting_started/intro_tutorials/03_subset_data.html#min-tut-03-subset)

[chrisjsewell]

So that was about the panels/cards, but the original issue here was about the "accordion". What are your current thoughts about that?

Yep, as mentioned above, the genesis of this was that over at AiiDA we are also re-vamping our documentation, and for the intro section I saw what you had done and thought "lets copy that" lol. Funnily enough I just found out we are also under the NumFocus Umbrella: http://www.aiida.net/news/aiida-becomes-numfocus-affiliated-project/; so its not copying, its sharing 😁
In doing this I have already drafted an accordion directive, currently internal to the AiiDA docs, that I intend to extract into a separate package.
I guess the question would be, is it easier/better to have a separate package for these individual directives, or perhaps change the name of sphinx-panels to something like sphinx-bootstrap, and have it be a "grab bag' of directives primarily focussed on directives related to bootstrap features

[choldgraf]

I think another use-case is the toggle-button:

right now that is all custom CSS / JS, but I think we could leverage bootstrap for this as well

[chrisjsewell]

The accordion and toggle-button are to some extent one and the same; just with different types of button. Both should be covered by https://getbootstrap.com/docs/4.3/components/collapse/.
Also some additional resources:

• https://www.w3schools.com/bootstrap/bootstrap_collapse.asp
• https://www.tutorialrepublic.com/twitter-bootstrap-tutorial/bootstrap-accordion.php

[jorisvandenbossche]

I think a sphinx-bootstrap would make sense to hold different of such directives (the panel, collapsable cards / accordion, also the general "div" directive might fit in there, ..). Making a separate package for each directive feels a bit like overkill (certainly if they can benefit of sharing the infrastructure of some bootstrap css that gets included or not).
(although a name like sphinx-panels is more descriptive than sphinx-bootstrap ..)

[choldgraf]

I'm gonna close this one, since I think the accordian functionality is / will be handled by sphinx-panels (maybe soon to be sphinx-components)