Add panels support

[12rambau]

Fix #627

as I'm still unable to build the doc on my machine, I'll use the draft to trigger the RDT build.

WIP

[choldgraf]

I'd use Sphinx Design, not Sphinx Panels (https://sphinx-design.readthedocs.io/en/latest/). The syntax is very similar though.

[12rambau]

I'd use Sphinx Design, not Sphinx Panels (https://sphinx-design.readthedocs.io/en/latest/). The syntax is very similar though.

Yep I saw your comment in the issue, as it's the same class I'll work with that for now and I'll update the lib name once everything works

[12rambau]

I think I now have something. I respected the structure initiated by @choldgraf and added 2 files in the extention folder. one to support sphinx-design and one for sphinx-panels fore legacy documentations.

In short you'll find in this PR:

• 2 sets of css rules to overwrite the one provided by sphinx-design and sphinx-panels extentions
• a new page to check the panels. I used sphinx-design for the examples
• some small modification to the navbar coloring to avoid being overwritten by other extention

several notes:

• the 2 extentions are fully incompatible as they both provide the :fa: role and are based on different versions of bootstrap
• I only support panels and tabs, the other components are less comonly used and should thus be customized by the user
• sphinx-design was easier to customize so I would prefer to use it instead of sphinx-panels
• there are a lot of !important rules due to the order of the files in the final html.

[choldgraf]

Thanks for this improvement! I added a few suggestions.

[choldgraf]

I know that sphinx-design uses many of its own CSS variables:

https://sphinx-design.readthedocs.io/en/latest/css_variables.html

If possible, I think it would be better to control the behavior here by using --pst variables to set --sd variables, rather than coding new CSS rules. Does that make sense?

[12rambau]

design-style .css is loaded after pydata-sphinx-theme one so I won't be able to overwrite anything (that's also why I need to use !important rules in lots of places). I think I can't.

  <!-- Loaded before other Sphinx assets -->
  <link href="_static/styles/theme.css?digest=fb52004a9691e5b75515" rel="stylesheet">
<link href="_static/styles/pydata-sphinx-theme.css?digest=fb52004a9691e5b75515" rel="stylesheet">

    
  <link rel="stylesheet"
    href="_static/vendor/fontawesome/5.13.0/css/all.min.css">
  <link rel="preload" as="font" type="font/woff2" crossorigin
    href="_static/vendor/fontawesome/5.13.0/webfonts/fa-solid-900.woff2">
  <link rel="preload" as="font" type="font/woff2" crossorigin
    href="_static/vendor/fontawesome/5.13.0/webfonts/fa-brands-400.woff2">

    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
    <link rel="stylesheet" type="text/css" href="_static/../_font/fontawesome/css/all.min.css" />
    <link rel="stylesheet" type="text/css" href="_static/../_font/fontawesome/css/all.min.css" />
    <link rel="stylesheet" type="text/css" href="_static/design-style.b7bb847fb20b106c3d81b95245e65545.min.css" />

[choldgraf]

hmmm yeah this feels related to @pradyunsg's concerns about !important in that library. @pradyunsg was there any way you got around this other than just !importanting everything?

[pradyunsg]

When two selectors have the same "specificity", then the latter definition is used. That's the situation here. You can work around this without !importants here by having a more specific selector -- like body .sd-card (that increases the specificity by 1, which might just be enough). :)

Most of the conflicting styles here aren't !important'd, so it's not a big deal. The issues I had with !important in that library are around this file: https://github.com/executablebooks/sphinx-design/blob/cca2cfb1b4c0a55ecf6661889c52ea320d42f58f/style/_display.scss

Furo has a separate furo-extensions.css file that is loaded after the extensions, to deal with some of this -- but realistically, unless you're overriding !importants (you're not, AFAICT), you can typically get away with a more specific selector. :)

[choldgraf]

Ooh that is a great point. Can we try increasing the specificity just a bit to see if we can add these fixes without the "important" lines?

[choldgraf]

I pushed a few minor changes to the docs:

• Moved the two sphinx-panels admonitions into a single one, so it's easier to read.
• Added an example of over-riding the sphinx-design primary color

I think the only thing remaining here is to see if we could remove some of the !important lines by making the CSS selectors more specific. Is that right @12rambau ?

[12rambau]

yep. I'm waiting for the ng-sphinx PR to be merged to use the new classes in the css files

[12rambau]

@choldgraf ready for review, no more !important to be seen.

[choldgraf]

Nice! This looks good to me, very happy there's no more !important!

[damianavila]

Is there a follow-up issue to get rid of sphinx-panels? I have not seen one yet.

[choldgraf]

I don't think so, but agree we should deprecate it and switch to Sphinx design!