diff --git a/_static/sphinx-hoverxref-demo.gif b/_static/sphinx-hoverxref-demo.gif new file mode 100644 index 00000000..7f5c196b Binary files /dev/null and b/_static/sphinx-hoverxref-demo.gif differ diff --git a/embedding-content-from-your-docs.rst b/embedding-content-from-your-docs.rst new file mode 100644 index 00000000..23c90a89 --- /dev/null +++ b/embedding-content-from-your-docs.rst @@ -0,0 +1,71 @@ +.. post:: June 23, 2020 + :tags: embed, sphinx, sphinx-extension, api + :author: Manuel + :location: BCN + +.. meta:: + :description lang=en: + Read the Docs allows you to embed content from any of the projects we host. + This allows reuse of content across sites, making sure the content is always up to date. + + +Embedding Content From Your Documentation +========================================= + +We are excited to announce the release of content embedding. +This allows users to embed content from any of the projects we host, *anywhere*. +Our approach to embedding content is a very simple but powerful idea: +*return the content of a specific section from a particular document in a project*. + +We have built an `Embed API`_ as the backend that powers this feature. +On top of this API, +we have built two improvements to the experience of our platform. + +.. _Embed API: https://docs.readthedocs.io/en/latest/api/v2.html#get--api-v2-embed- + +Contextualized tooltips on documentation pages +---------------------------------------------- + +Our first goal was adding extra context to a link within the same page. +This helps the reader understand a concept, +without switching context and jumping into another completely different page. + +Documentation is already full of links to additional content, +and with the new Embed API that can return that exact content, +we thought *let's add a tooltip with this content when the reader hovers the link!* +That's how `sphinx-hoverxref`_ was born. + +``sphinx-hoverxref`` allows documentation authors to easily add these tooltips, +customize their style, and decide which elements will show tooltips. +We recommend `reading the docs`_ to see everything it can do. + +.. figure:: /_static/sphinx-hoverxref-demo.gif + + Example of ``sphinx-hoverxref`` on Read the Docs documentation. + +.. _sphinx-hoverxref: https://sphinx-hoverxref.readthedocs.io/ +.. _reading the docs: https://sphinx-hoverxref.readthedocs.io/ + +Inline help on our application website +-------------------------------------- + +Adding too much copy in your application can be overwhelming to users, +meaning they don't read it. +We try to keep the application copy minimal, and link out to documentation when appropriate. +This pattern has worked fine over time, but it has the same problem of context switching to a completely different page. + +Since we've started working on a new re-design of our entire application UI (more on this coming soon!), +we added the usage of the Embed API to add this extra documentation. +By adding a tooltip to our documentation links, +we allow the user to maintain the content in our application but also learn more about the features they are using. + +In summary +---------- + +If you liked the Embed API and you would like to embed content from your documentation anywhere, +you can `read its full documentation`_ to learn more about it. + +.. _read its full documentation: https://docs.readthedocs.io/en/stable/guides/embedding-content.html + +We think it's a super powerful feature and we encourage you to use the extension we built on top of it, +or even better, build your own and share them with us!