Enter OEmbed – “[..] an open format designed to allow embedding content from a website into another page.”
It allows content providers such as Youtube to provide API endpoints that return a chunk of HTML content that represents how they want it to be rendered and embedded elsewhere. In other words, my blog would be able to ask Youtube behind the scenes how a given movie should show up on my side. That’s especially useful for those content providers that require complex HTML snippets with Flash applets or similar. OEmbed simply made a lot of content providers to agree on how such an query would work. See Leah’s article from 2008 (!) about announcing the format for more information.
The main problem with OEmbed though is that when you try to use OEmbed you actually have to maintain a list of content provider that you want to be able to integrate content from. There isn’t a central registry of which website supports OEmbed so it’s left to the user to handle it technically. There are many different solutions to this, like a shared list of providers, or hardcoded ones in case of Django apps like django-oembed (or similar).
Luckily some smart people started to implement that missing central registry and called it Embedly. They take care of keeping a database of supported websites up-to-date and built a nice set of services around. Additionally they offer some features that were out of the scope of the OEmbed format such as security related features with regard to iFrame embeds and SSL based websites. They have a great oEmbed API and provide a nice little Python library (next to dozens others).
So now I have blog posts written in reStructuredText format and a service that I can query via its API to replace links to external sites in that content with the real representation. All I needed to do is write a small piece of software to bridge both of those, if possible in a way that it would allow me to reuse it.
It allows content providers such as Youtube to provide API endpoints that return a chunk of HTML content that represents how they want it to be rendered and embedded elsewhere. In other words, my blog would be able to ask Youtube behind the scenes how a given movie should show up on my side. That’s especially useful for those content providers that require complex HTML snippets with Flash applets or similar. OEmbed simply made a lot of content providers to agree on how such an query would work. See Leah’s article from 2008 (!) about announcing the format for more information.
The main problem with OEmbed though is that when you try to use OEmbed you actually have to maintain a list of content provider that you want to be able to integrate content from. There isn’t a central registry of which website supports OEmbed so it’s left to the user to handle it technically. There are many different solutions to this, like a shared list of providers, or hardcoded ones in case of Django apps like django-oembed (or similar).
Luckily some smart people started to implement that missing central registry and called it Embedly. They take care of keeping a database of supported websites up-to-date and built a nice set of services around. Additionally they offer some features that were out of the scope of the OEmbed format such as security related features with regard to iFrame embeds and SSL based websites. They have a great oEmbed API and provide a nice little Python library (next to dozens others).
So now I have blog posts written in reStructuredText format and a service that I can query via its API to replace links to external sites in that content with the real representation. All I needed to do is write a small piece of software to bridge both of those, if possible in a way that it would allow me to reuse it.
sphinxcontrib-embedly
This is why I released sphinxcontrib-embedly. It’s a hybrid docutils/Sphinx extension for embedding any content supported by Embedly (~250 providers as of writing this article). Obviously there are some caveats when using Sphinx during rendering (e.g. it hardly will work when rendering PDFs). But I think the majority of Sphinx users will find it useful nevertheless.Here’s how a reStructureText snippet using that extension looks like:
.. embedly:: http://www.youtube.com/watch?v=M_eYSuPKP3Y
:width: 600
There are tons of other options you can pass the embedly directive:
.. embedly:: <url>
:maxwidth: integer (no default)
:maxheight: integer (no default)
:width: integer (no default)
:wmode: "window", "opaque" or "transparent" (no default)
:nostyle: true or false (default)
:autoplay: true or false (default)
:videosrc: true or false (default)
:words: integer (default 50)
:chars: integer (default 100)
:frame: true or false (default, available with paid product)
:secure: true or false (default, available with paid product)
from https://jezdez.com/2014/01/26/embedding-external-content-in-rst/
related post: http://briteming.blogspot.com/2013/11/linux-vpspythonhandcrank.html
