jupyter-book icon indicating copy to clipboard operation
jupyter-book copied to clipboard

Update `sphinx-panels` to `sphinx-design`

Open choldgraf opened this issue 4 years ago • 2 comments

Context

sphinx-panels is currently what defines our more "UI-ish" elements, but it has been superceded by sphinx-design and so we should update Jupyter Book to use this instead.

Here are our docs for panels functionality

Implementation details

  • Here's an issue tracking some changes from sphinx-panels to sphinx-design: https://github.com/executablebooks/sphinx-design/issues/51
  • Here's the documentation for migrating from sphinx-panels: https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html#migrating-from-sphinx-panels

Tasks to complete

  • [x] Confirm that the two packages have feature parity for the things we have documented in Jupyter Book
  • [x] Swap out sphinx-design for sphinx-panels in the Jupyter Book docs
  • [x] Update our docs for whatever new syntax it uses
  • [x] Update our tests for whatever new outputs it creates
  • [x] Figure out what kind of deprecation pathway we want
    • One idea: provide documentation for how users could disable sphinx-design and enable sphinx-panels and then remove that after a release or two.

This is now implemented

Check out the docs and links for migration guides

  • here: https://sphinx-design.readthedocs.io/en/latest/get_started.html#migrating-from-sphinx-panels
  • and here: https://github.com/executablebooks/sphinx-design/issues/51

choldgraf avatar Oct 31 '21 17:10 choldgraf

@chrisjsewell to best approximation, is sphinx-design at a point where we could give this a shot and add it in to Jupyter Book, or do you imagine the API changing? Trying to figure out if it is "ready for active use" from your perspective

choldgraf avatar Oct 31 '21 17:10 choldgraf

~~Hey folks! Is there a plan for a "migration guide" for the elements previously provided by sphinx-panels and how they might now work with sphinx-design?~~

EDIT: Found it here https://sphinx-design.readthedocs.io/en/latest/get_started.html#migrating-from-sphinx-panels 😄

melissawm avatar Jun 09 '22 12:06 melissawm