Sphinx theme with breathe support

[dantownsend]

Hi! I maintain a Sphinx theme called Piccolo theme.

In the latest version, a contributor added some custom JS and CSS to make C++ snippets from breathe look nice. Here's a demo.

Just sharing in case it's useful for others, thanks!

[vermeeren]

@dantownsend Thanks for sharing!

@2bndy5 FYI Considering recent work in #820 you might find something useful here. The Piccolo ref is piccolo-orm/piccolo_theme#17.

[2bndy5]

I also help maintain the sphinx theme called sphinx-immaterial. And the only reason I didn't recommend that theme is because how the C/C++ API ends up looking for multi-line/long signatures.

In sphinx-immaterial, we also try to put long signatures (identified as anything over 72 characters) into multiple lines. But so far our approach has been purely CSS. We would prefer a more programmatic approach, but that would have to be very language (also known in sphinx as "domain") dependent.

@dantownsend your theme does use a programmatic approach in long signatures (exclusively for py and cpp domains only), but it does that using JS to alter the live
DOM. This approach is also not very performant because that JS is called when the reader loads the page.

I don't mean to sound completely negative, rather I found the approach a bit inspiring. I foresee the JS approach working with template parameters as well. And it doesn't care about the length of the signature - all signatures get multiple lines if there are at least 2 parenthesises (identified as CSS class .sig-paren not as actual ( and )).

---

After looking through the code and the demo, I'm not going to change my proposal to use the furo theme because that theme is just more "seasoned". The piccolo theme has some material design aesthetics that haven't been implemented yet (like shading the page's body content when a side navigation bar is expanded - see modal drawer spec in material.io)

[dantownsend]

I'm glad it provided some inspiration. The JS is fairly lightweight by modern standards, but I agree that doing it without JS would be preferable.

Furo is a great theme, and I can see why you picked it.

I've updated the README of the Piccolo theme to mention that it's not Material Design. I can see why people would think that, but it's not the goal.

[2bndy5]

So there won't be any visual distinction between side menus and main content?

In trying the demo, I found it weird that the only way to close the side menus is by using the button that opened the menu. This also leads to accidental misuse of the UI. For example, I'm able to open both side menus simultaneously.

[dantownsend]

It's just personal preference I guess. I don't mind being able to open both menus.

[2bndy5]

That was just an example. Your readers could accidentally tap on a hyperlink within the page's body content while the side menus are open. I'm not sure if I like your "personal preference".

Material design has become such a modern standard, but I guess I've become spoiled by the widespread adoption.

[dantownsend]

Thanks for your input.

[2bndy5]

Ironically, I recently had to use a similar JS-based approach when developing a theme for Doxygen HTML output. There's a feature slated for Doxygen v2.0 that should allow using template engines like Django or Jinja. Such a feature may deem this breathe extension as a less ideal solution to prettify Doxygen's horrid default HTML output 🤞