search

wpilibsuite / sphinxext-opengraph

Sphinx extension to generate unique OpenGraph metadata
https://sphinxext-opengraph.readthedocs.io
Other
69 stars 25 forks source link

Add `:ogp_disable:` metadata field #86

Closed shiftinv closed 10 months ago

shiftinv commented 1 year ago

Adds a way of disabling opengraph tags per-page using an :ogp_disable: field.

We've had a need for something like this on things like API reference pages, which don't necessarily have a proper description and/or shouldn't have og tags for other reasons. This is more of a proposal and I'd understand if you don't want to add something like this, but it would be a step up from our current, somewhat hacky solution of hooking into the html-page-context callback :)

TheTripleV commented 1 year ago

I'm assuming you'd still want some kind of nice embed on Twitter/Discord.

Wouldn't it be better for your API documentation to specify a custom title/description for that one page?

Daltz333 commented 1 year ago

A possible strategy would be generating a bunch of stubs per function/variable/etc definition and have that redirect to a href reference of the original location. Things like discourse do this.

shiftinv commented 1 year ago

I'm assuming you'd still want some kind of nice embed on Twitter/Discord.

Wouldn't it be better for your API documentation to specify a custom title/description for that one page?

True that. Essentially, the core idea is to disable embeds for that page entirely to avoid clutter, since the description shown when linking to any symbol would always be the same and not particularly helpful; it's a pretty niche use case, admittedly.

A possible strategy would be generating a bunch of stubs per function/variable/etc definition and have that redirect to a href reference of the original location. Things like discourse do this.

I considered that as well, it'd be one of the best solutions in most cases. With the static nature of Sphinx however that would mean generating several hundred stub files - in our case, a quick document.querySelectorAll(".py.class").length currently yields about 225 elements, or ~1500 if attributes are also taken into account.