disnake
disnake copied to clipboard
DisnakeDev
docs: add opengraph metadata tags
Summary
Adds sphinxext-opengraph to generate Open Graph metadata on all docs pages.
As an example, the resulting Discord embed looks like this:
~~Depends on https://github.com/wpilibsuite/sphinxext-opengraph/pull/86 for now, but we're in no rush to add this anyway.~~
Checklist
- [ ] If code changes were made, then they have been tested
- [ ] I have updated the documentation to reflect the changes
- [ ] I have formatted the code properly by running
task lint - [ ] I have type-checked the code by running
task pyright
- [ ] This PR fixes an issue
- [ ] This PR adds something new (e.g. new method or parameters)
- [ ] This PR is a breaking change (e.g. methods or parameters removed/renamed)
- [x] This PR is not a code change (e.g. documentation, README, ...)
Since the upstream PR this is waiting on has been stalled for a while now, I've decided to go with the slightly more ~~fun~~ complicated way of patching the event directly for now, adding on to the pile of sphinx hacks that are already there :p
If (and that's a big if, I'd understand if the maintainers don't want to add this feature) the other PR gets merged at some point, we can always update to that.
I've changed it to generate more concise descriptions, by only taking the first section into account.
The :ogp_disable: logic was also removed for now, as #722 changed things up quite a bit - should opengraph metadata be disabled for API reference pages again?
Since a common use-case is linking to specific items on those pages, and opengraph obviously doesn't account for that, those embeds aren't all that useful right now:
Perhaps we can launch it on all pages, and remove it from API reference pages if it turns out to not work too well. (We won't know unless we try it)
Perhaps we can launch it on all pages, and remove it from API reference pages if it turns out to not work too well. (We won't know unless we try it)
Sound good to me, then.