DOC: add sphinxext-opengraph #20464
DOC: add sphinxext-opengraph #20464
Conversation
GaelVaroquaux
force-pushed the
GaelVaroquaux:open_graph
branch
2 times, most recently
from
ee85029
to
3e1e6d8
sphinxext-opengraph creates social-network thumbnails and summaries. Hence it makes scikit-learn online presence more visible and readable. The drawback is an added dependency (sphinxext-opengraph) to build the doc.
|
In the MOOC forum (discourse), I saw that we did not get any preview and it could be a plus. |
|
If adding a dependency to the doc building is an issue, we could make this optional: we can try to import the relevant package in conf.py and add it only if it imports. Hence doc building could pursue without the package (eg for local builds). |
|
IMHO adding such a dependency for the docs isn't too critical, it's fine to add it We should update the docs' docs though: https://scikit-learn.org/stable/developers/contributing.html#building-the-documentation |
|
+1 as well. Did a few tests, In linkedin without this extension this page renders as,
however I'm getting an identical (i.e. not great) rendering with this PR. In slack In twitter Without this no preview, with it (at least in DM). So it's clearly an improvement, but we might still want to tune it in the future. In particular the logo is currently never shown. |
The tags added by the extension uses a relative URL. For the image to work everywhere, I think it needs the absolute path:
There is already a bug report here: wpilibsuite/sphinxext-opengraph#43 As for adding a dependency, much of the tags are easy to add by adjusting our template. The harder part is parsing the description + finding the first image, which is the value add from REF: I usually check metatags using: https://metatags.io/ |
|
LGTM with or without making it an optional dependency. If we don't make it an optional dependency we need to update the documentation related to building the documentation instead: https://scikit-learn.org/dev/developers/contributing.html#building-the-documentation |
|
BTW, doc requirements in https://scikit-learn.org/dev/developers/contributing.html#building-the-documentation install 41 packages. I don't think one more or less is going to matter. |
|
I'll update the build requirement and try to get the logo working. |
|
OK, I documented the added dependency. Couldn't fix the logo this. If anyone has an idea, I'm interested. Else, I believe that this is ready for merge. |
|
Thanks @GaelVaroquaux |
NicolasHug
merged commit 5a879f4
into
scikit-learn:main
|
Thanks everybody for the comments and review! |
sphinxext-opengraph creates social-network thumbnails and summaries.
Hence it makes scikit-learn online presence more visible and readable.
The drawback is an added dependency (sphinxext-opengraph) to build the doc.
This PR is just a test to demo the functionality and see if we like it.
Under mattermost (and slack, and other social networks) it produces previews as such:
