Doc: Add macro for embedding YouTube videos

This macro adds a \youtube <ID> command that embeds a YouTube link
into the documentation.

The video container scales to a specified percentage of the available
horizontal area. It assumes a source aspect ratio of 16:9, but looks
acceptable with other ratios.

For backends that do not support <iframe> (e.g. QTextBrowser), shows
a clickable video thumbnail that open the YouTube link in an external
browser window. Unfortunately, QTextBrowser cannot load images from
a remote URL, so we need to store a thumbnail image in the .qch file.

Change-Id: I3a3a0c5a20dd90e5cec6357ba70a23ee47dbe825
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

4 files changed, 57 insertions, 0 deletions

diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf
index 1182af14e9..5544da425a 100644
--- a/doc/global/macros.qdocconf
+++ b/doc/global/macros.qdocconf
@@ -38,3 +38,17 @@ macro.beginfloatright.HTML  = "<div style=\"float: right; margin-left: 2em\">"
 macro.endfloat.HTML         = "</div>"
 macro.clearfloat.HTML       = "<br style=\"clear: both\" />"
 macro.emptyspan.HTML        = "<span></span>"
+
+# Embed YouTube content by video ID - Example: \youtube dQw4w9WgXcQ
+# Also requires a <ID>.jpg thumbnail for offline docs. In .qdocconf, add:
+#
+# HTML.extraimages           += images/dQw4w9WgXcQ.jpg
+# qhp.ProjectName.extraFiles += images/dQw4w9WgXcQ.jpg
+#
+macro.youtube.HTML = "<div class=\"video\">\n<span class=\"vspan\"></span>\n" \
+                     "<iframe src=\"https://www.youtube.com/embed/\1\"" \
+                     "frameborder=\"0\" allowfullscreen>\n" \
+                     "<a href=\"https://www.youtube.com/watch/?v=\1\">\n"\
+                     "<img src=\"images/\1.jpg\"" \
+                     "title=\"Click to play in a browser\" /></a>\n" \
+                     "</iframe></div>\n"
diff --git a/doc/global/template/style/offline-simple.css b/doc/global/template/style/offline-simple.css
index a805b924a3..043e42981d 100644
--- a/doc/global/template/style/offline-simple.css
+++ b/doc/global/template/style/offline-simple.css
@@ -160,3 +160,7 @@ td#buildversion {
 .footer p {
   margin: 0px;
 }
+
+.video {
+  margin: 15px 0 0 15px;
+}
diff --git a/doc/global/template/style/offline.css b/doc/global/template/style/offline.css
index e2081596c9..a65cf48d91 100644
--- a/doc/global/template/style/offline.css
+++ b/doc/global/template/style/offline.css
@@ -780,3 +780,23 @@ div.multi-column div {
     margin-right: 4em;
     width: 24em;
 }
+
+.mainContent .video {
+  width:40%;
+  max-width:640px;
+  margin: 15px 0 0 15px;
+  position:relative;
+  display:table
+}
+
+.mainContent .video > .vspan {
+  padding-top:60%;
+  display:block
+}
+.mainContent .video iframe {
+  width:100%;
+  height:100%;
+  position:absolute;
+  top:0;
+  left:0
+}
diff --git a/doc/global/template/style/online.css b/doc/global/template/style/online.css
index 3c305f3ddb..2d758f5301 100644
--- a/doc/global/template/style/online.css
+++ b/doc/global/template/style/online.css
@@ -1721,3 +1721,22 @@ a.qa-mark:target:before {
   color: #ff0000;
 }
 
+.mainContent .video {
+  width:60%;
+  max-width:640px;
+  margin: 0.5em 0 1.5em 0.5em;
+  position:relative;
+  display:table
+}
+
+.mainContent .video > .vspan {
+  padding-top:60%;
+  display:block
+}
+.mainContent .video iframe {
+  width:100%;
+  height:100%;
+  position:absolute;
+  top:0;
+  left:0
+}