docs: add youtube videos to docs

Author: eitanlees

doc/_static/custom.css

@@ -23,4 +23,37 @@ table.docutils td p {
 table.docutils td li {
   line-height: 18px;
 
-}
+}
+
+/* Elevation
+*
+* The box-shadows style is from Material Design's idea of elevation. These particular numbers are taken from here:
+*
+* https://github.com/material-components/material-components-web
+* https://material-components-web.appspot.com/elevation.html
+*
+* The div.youtube-video styling is done to get the YouTube video to size dynamically
+* to 100% of the content width.
+ */
+
+.rst-content div.youtube-video {
+  position: relative;
+  width: 100%;
+  height: 0px;
+  /* This must be equal to the inverse of the aspect ratio of the video */
+  /* The current value is: 56.25% = 315/560 */
+  padding-bottom: 56.25%;
+  border: none;
+  /* MD Elevation 8 */
+  box-shadow: 0px 5px 5px -3px rgba(0, 0, 0, 0.2),
+    0px 8px 10px 1px rgba(0, 0, 0, 0.14), 0px 3px 14px 2px rgba(0, 0, 0, 0.12);
+  margin-bottom: 24px;
+}
+
+.rst-content div.youtube-video iframe {
+  position: absolute;
+  left: 0px;
+  top: 0px;
+  width: 100%;
+  height: 100%;
+}

doc/getting_started/overview.rst

@@ -31,5 +31,13 @@ handled automatically. Building on this declarative plotting idea, a surprising
 of simple to sophisticated plots and visualizations can be created using a relatively
 concise grammar.
 
+For a more detailed overview of the Altair's visualization grammar, see the following
+
+.. raw:: html
+
+  <div class="youtube-video">
+    <iframe src="https://www.youtube-nocookie.com/embed/U7w1XumKK60?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
+  </div>
+
 .. _Vega: http://vega.github.io/vega
 .. _Vega-Lite: http://vega.github.io/vega-lite

doc/user_guide/encoding.rst

@@ -173,6 +173,15 @@ or more.
 Specifying the correct type for your data is important, as it affects the
 way Altair represents your encoding in the resulting plot.
 
+The following video is a brief overview of Altair's data types. 
+
+.. raw:: html
+
+  <div class="youtube-video">
+    <iframe src="https://www.youtube-nocookie.com/embed/LSEPyCqjoAg?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
+  </div>
+
+
 .. _type-legend-scale:
 
 Effect of Data Type on Color Scales

doc/user_guide/internals.rst

@@ -18,6 +18,14 @@ That's it. In order to take those specifications and turn them into actual
 visualizations requires a frontend that is correctly set up, but strictly
 speaking that rendering is generally not controlled by the Altair package.
 
+Below is a short explaination about Altair and the software stack it is built on for more context. 
+
+.. raw:: html
+
+  <div class="youtube-video">
+    <iframe src="https://www.youtube-nocookie.com/embed/AAuPPorsmJc?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
+  </div>
+
 Altair chart to Vega-Lite Spec
 ------------------------------
 Since Altair is fundamentally about constructing chart specifications, the central