Add modern components from the Sphinx ecosystem

[amotl]

About

This patch adds a few modern components from the Sphinx ecosystem to the theme, and demonstrates how they are used. Thanks to all the authors for your excellent work.

• myst-parser, see also Introduction: MyST Markdown - Markedly Structured Text ✍️.
• sphinx-design
• sphinx-design-elements
• sphinx-inline-tabs
• sphinx-subfigure
• sphinx-togglebutton
• sphinxcontrib-mermaid

Preview

The preview of the demonstration pages can be inspected at RTD: CrateDB docs theme » Preview. There is a dedicated section demonstrating how to use the corresponding modern Sphinx components, elements, and styles.

https://crate-docs-theme--378.org.readthedocs.build/en/378/#modernized

[matkuliak]

Hello @amotl this is great, thank you!
I noticed you suggest removal of sphinx_copybutton. Why is that? Is it part of some of the newly added components?

[amotl]

I noticed you suggest removal of sphinx_copybutton.

That would not have been intended. Please add an inline comment on the PR where you discovered this spot.

[seut]

Great! 👍

[hlcianfagna]

FYI @hammerhead , @karynzv

[amotl]

It looks like the Markdown/MyST markup instruction to quote/cite text does not render properly yet. /cc @msbt

-- https://crate-docs-theme--378.org.readthedocs.build/en/378/myst-overview.html#inline-quotes-citations

[msbt]

@amotl do we have an example on how that's supposed to look like? We probably need to remove some css from the original theme to make this work

[matkuliak]

Not sure for our theme, but in general:

• https://pradyunsg.me/furo/reference/text-formatting/#text-formatting (The "This is blockquoted text." at the bottom)
  • https://github.com/pradyunsg/furo/blob/main/docs/reference/text-formatting.md?plain=1#L11
• https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax.html#math-in-other-block-elements ("A block quote $a=1
  $")
  • https://github.com/executablebooks/MyST-Parser/blob/master/docs/syntax/optional.md?plain=1#L209

[amotl]

Exactly. It is written like

> Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.

and usually renders like

Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.

[matkuliak]

I guess this is the issue:

• https://github.com/crate/crate-docs-theme/blob/main/src/crate/theme/rtd/crate/static/css/crateio-rtd.css#L27
• https://github.com/crate/crate-docs-theme/blob/main/src/crate/theme/rtd/crate/static/css/components.css#L187

A missing border, right?

[amotl]

Looks good, I think you found the right spot, thanks. 🙇

[msbt]

@matkuliak @amotl https://github.com/crate/crate-docs-theme/blob/main/src/crate/theme/rtd/crate/static/css/crateio-rtd.css#L27-L31 is indeed the main issue, if we remove those lines, the quote works. But if you have a paragraph wrapped in there, we might also need to override the margin-bottom, else it won't be centered vertically:

Should I whip something up? And can you check if we're actually using the current blockquote somewhere in the docs @matkuliak?

[amotl]

Should I whip something up?

Please go ahead. Thanks!

[amotl]

Thank you for submitting GH-380, aiming to fix this.

[amotl]

I think this works well now, right?

• https://crate-docs-theme--378.org.readthedocs.build/en/378/rst/misc.html
• https://crate-docs-theme--378.org.readthedocs.build/en/378/myst/misc.html

Thank you again.

[amotl]

Apparently, the .. todo directive renders itself with a bit too much of a left padding or margin. Maybe we can do something about it on a future iteration. It is not too important right now.

-- https://crate-docs-theme--378.org.readthedocs.build/en/378/rst/misc.html
-- https://crate-docs-theme--378.org.readthedocs.build/en/378/myst/misc.html

[amotl]

Created GH-381 in order to track this issue.