Httpdomain extensions

[AWhetter]

This is a proof of concept to add some richer navigation to endpoints documented with the httpdomain Sphinx extension. This may be something better suited as another extension that can be installed alongside sphinx-rtd-theme, but I thought it would be worth checking if it has a place here first.

When documenting HTTP endpoints the sections can get quite large. This extension collapses documented HTTP endpoints by default. When you click on an endpoint, it will expand out. I have included a gif screenshot of the extension in action. The extension also colours the endpoints by which HTTP method it relates to.

P.S. I'm not a fontend dev so please excuse my terrible sass/js practices ;)

[agjohnson]

I don't yet have time for a proper review, but I think the CSS styles would be a good addition -- it's great to have consistency across sphinx domains and similar pieces.

The JS is something I'd rather we don't maintain here. That feels like functionality that should be in the httpdomain extension if anything.

[AWhetter]

I would be happy with only the CSS making it's way in.
Should I trim this pull request down to just the CSS or shall we wait a bit to collect more opinions on this discussion first?

[AWhetter]

Having thought about this a little further, I am less sure if splitting up the CSS and the javascript makes sense. Or at least we can't split those two parts so easily.

Part of the CSS adds a border to the endpoint banner when hovered over to indicate to the user that it can be interacted with. It's only one line of the CSS, but it could be argued that even the size of the border that should show is part of the theme? I'm not sure. But this part of the CSS definitely belongs with the javascript.

A part of the javascript affects the look of the endpoint banners. The summary line is brought up into banner itself. This happens mostly to make navigation of collapsed banners much easier, so maybe it only makes sense to live with the collapsing javascript?

Something we would probably want to do regardless is make the collapsing configurable. Either through a config option or by using the class directive to add a collapsible class to endpoints.

I will open an issue with httpdomain and get their thoughts. To be honest if we decide that this doesn't belong in here, I think it should be it's own package.

[agjohnson]

Good points. I could definitely see the theme providing it's own styling to make extensions like this fit the look and feel of the theme, so perhaps it might ultimately live in both places?

I'll set this to blocking for now, let us know what you decide would be best!

[AWhetter]

I suppose unsurprisingly I haven't had a response from httpdomain. It looks like the extension doesn't get much attention anymore.

Going back to the idea about the theme providing styling for extensions to use, I think what would be needed for this idea to work is:
A way to add a class to a banner that will add a shadow. The theme can decide the style and colour of the border.
A way to use different colours in a banner from some palette of colours that the theme provides.

It means that extensions would have a "bootstrap style" way of making additions and customisations to the theme.

Everything to do with collapsing and the summary line wrapping is something that should live in the extension I think.

[AWhetter]

Closing because I've released these changes as a separate sphinx extension.