Allow promos to be placed in the docs footer (#3267)

- this is in addition to the normal left navigation
- works on the RTD and Alabaster themes

media/css/readthedocs-doc-embed.css

@@ -8,21 +8,21 @@
 }
 
 .rst-other-versions {
-	text-align: left;
+    text-align: left;
 }
 
 .rst-other-versions a {
-	border: 0;
+    border: 0;
 }
 
 .rst-other-versions dl {
-	margin: 0;
+    margin: 0;
 }
 
 
 /* Fix RTD theme bottom margin */
 .rst-content .line-block {
-	margin-bottom: 24px
+    margin-bottom: 24px
 }
 
 /* Fix for nav bottom padding with flyout */
@@ -134,11 +134,39 @@ div.rtd-pro.alabaster div.rtd-pro-about a {
     border-bottom: 0px;
 }
 
-div.rtd-pro.alabaster div.rtd-pro-about i.fa-info-circle:before {
+div.rtd-pro.alabaster div.rtd-pro-about i.fa-info-circle:before,
+div.rtd-pro.rtd-pro-footer div.rtd-pro-about i.fa-info-circle:before {
     content: "";
     color: #a3a3a3;
 }
 
+/* Hide the "sponsored" note in the left navigation */
+div.rtd-pro-about span {
+    display: none;
+}
+
+/* Footer promos */
+div.rtd-pro.rtd-pro-footer div.rtd-pro-about span {
+    display: inline;
+}
+div.rtd-pro.rtd-pro-footer div.rtd-pro-about {
+    float: none;
+}
+div.rtd-pro.rtd-pro-footer div.rtd-pro-about a {
+    text-decoration: none;
+}
+div.rtd-pro.rtd-pro-footer {
+    text-align: left;
+}
+div.rtd-pro.rtd-pro-footer a.rtd-pro-image-wrapper {
+    float: right;
+    margin-left: 25px;
+}
+
+div.rtd-pro-wrapper {
+    clear: both;
+}
+
 @media (max-width: 768px) {
     div.rst-pro.wy-menu {
         display: none;

readthedocs/core/static-src/core/js/doc-embed/constants.js

@@ -10,4 +10,9 @@ exports.PROMO_SUPPORTED_THEMES = [
     exports.THEME_ALABASTER
 ]
 
+exports.PROMO_TYPES = {
+    LEFTNAV: 'doc',               // Left navigation on documentation pages
+    FOOTER: 'site-footer'         // Footer of documentation pages
+};
+
 module.exports = exports;

readthedocs/core/static-src/core/js/doc-embed/footer.js

@@ -73,7 +73,8 @@ function injectFooter(data) {
             data.promo_data.text,
             data.promo_data.link,
             data.promo_data.image,
-            config.theme
+            config.theme,
+            data.promo_data.display_type
         )
         if (promo) {
             promo.display();

readthedocs/core/static-src/core/js/sponsorship.js

@@ -6,13 +6,24 @@ module.exports = {
     Promo: Promo
 };
 
-function Promo (id, text, link, image, theme) {
+function Promo (id, text, link, image, theme, display_type) {
     this.id = id;
     this.text = text;
     this.link = link;
     this.image = image;
     this.theme = theme || constants.THEME_RTD;
+    this.display_type = display_type || constants.PROMO_TYPES.LEFTNAV;
     this.promo = null;
+
+    // Handler when a promo receives a click
+    this.click_handler = function () {
+        if (_gaq) {
+            _gaq.push(
+                ['rtfd._setAccount', 'UA-17997319-1'],
+                ['rtfd._trackEvent', 'Promo', 'Click', self.id]
+            );
+        }
+    };
 }
 
 Promo.prototype.create = function () {
@@ -20,93 +31,112 @@ Promo.prototype.create = function () {
         menu,
         promo_class;
     if (this.theme == constants.THEME_RTD) {
-        menu = this.get_sphinx_rtd_theme_menu();
-        promo_class = 'wy-menu';
+        menu = this.get_sphinx_rtd_theme_promo_selector();
+        promo_class = this.display_type === constants.PROMO_TYPES.FOOTER ? 'rtd-pro-footer' : 'wy-menu';
     }
     else if (this.theme == constants.THEME_ALABASTER) {
-        menu = this.get_alabaster_menu();
-        promo_class = 'alabaster';
+        menu = this.get_alabaster_promo_selector();
+        promo_class = this.display_type === constants.PROMO_TYPES.FOOTER ? 'rtd-pro-footer' : 'alabaster';
     }
+
     if (typeof(menu) != 'undefined') {
-        // Add elements
-        promo = $('<div />')
-            .attr('class', 'rtd-pro ' + promo_class);
-
-        // Promo info
-        var promo_about = $('<div />')
-            .attr('class', 'rtd-pro-about');
-        var promo_about_link = $('<a />')
-            .attr('href', 'https://readthedocs.org/sustainability/advertising/')
-            .appendTo(promo_about);
-        var promo_about_icon = $('<i />')
-            .attr('class', 'fa fa-info-circle')
-            .appendTo(promo_about_link);
-        promo_about.appendTo(promo);
-
-        // On Click handler
-        function promo_click() {
-            if (_gaq) {
-                _gaq.push(
-                    ['rtfd._setAccount', 'UA-17997319-1'],
-                    ['rtfd._trackEvent', 'Promo', 'Click', self.id]
-                );
-            }
-        }
-
-        // Promo image
-        if (self.image) {
-            var promo_image_link = $('<a />')
-                .attr('class', 'rtd-pro-image-wrapper')
-                .attr('href', self.link)
-                .attr('target', '_blank')
-                .on('click', promo_click);
-            var promo_image = $('<img />')
-                .attr('class', 'rtd-pro-image')
-                .attr('src', self.image)
-                .appendTo(promo_image_link);
-            promo.append(promo_image_link);
-        }
-
-        // Create link with callback
-        var promo_text = $('<span />')
-            .html(self.text);
-        $(promo_text).find('a').each(function () {
-            $(this)
-                .attr('class', 'rtd-pro-link')
-                .attr('href', self.link)
-                .attr('target', '_blank')
-                .on('click', promo_click);
-        });
-        promo.append(promo_text);
-
-        promo.appendTo(menu);
-
-        promo.wrapper = $('<div />')
-            .attr('class', 'rtd-pro-wrapper')
-            .appendTo(menu);
-
-        return promo;
+        this.place_promo(menu, promo_class);
     }
 }
 
-Promo.prototype.get_alabaster_menu = function () {
+Promo.prototype.place_promo = function (selector, promo_class) {
+    var self = this;
+
+    // Add elements
+    var promo = $('<div />')
+        .attr('class', 'rtd-pro ' + promo_class);
+
+    // Promo info
+    var promo_about = $('<div />')
+        .attr('class', 'rtd-pro-about');
+    var promo_about_link = $('<a />')
+        .attr('href', 'https://readthedocs.org/sustainability/advertising/')
+        .appendTo(promo_about);
+    $('<span />').text('Sponsored ').appendTo(promo_about_link);
+    var promo_about_icon = $('<i />')
+        .attr('class', 'fa fa-info-circle')
+        .appendTo(promo_about_link);
+    promo_about.appendTo(promo);
+
+    // Promo image
+    if (self.image) {
+        var promo_image_link = $('<a />')
+            .attr('class', 'rtd-pro-image-wrapper')
+            .attr('href', self.link)
+            .attr('target', '_blank')
+            .on('click', this.click_handler);
+        var promo_image = $('<img />')
+            .attr('class', 'rtd-pro-image')
+            .attr('src', self.image)
+            .appendTo(promo_image_link);
+        promo.append(promo_image_link);
+    }
+
+    // Create link with callback
+    var promo_text = $('<span />')
+        .html(self.text);
+    $(promo_text).find('a').each(function () {
+        $(this)
+            .attr('class', 'rtd-pro-link')
+            .attr('href', self.link)
+            .attr('target', '_blank')
+            .on('click', this.click_handler);
+    });
+    promo.append(promo_text);
+
+    promo.appendTo(selector);
+
+    promo.wrapper = $('<div />')
+        .attr('class', 'rtd-pro-wrapper')
+        .appendTo(selector);
+
+    return promo;
+};
+
+Promo.prototype.get_alabaster_promo_selector = function () {
+    // Return a jQuery selector where the promo goes on the Alabaster theme
     var self = this,
-        nav_side = $('div.sphinxsidebar > div.sphinxsidebarwrapper');
+        selector;
 
-    if (nav_side.length) {
-        return nav_side;
+    if (self.display_type === constants.PROMO_TYPES.FOOTER) {
+        selector = $('<div />')
+            .attr('class', 'rtd-pro-footer-wrapper body')
+            .appendTo('div.bodywrapper');
+        $('<hr />').insertBefore(selector);
+        $('<hr />').insertAfter(selector);
+    } else {
+        selector = $('div.sphinxsidebar > div.sphinxsidebarwrapper');
     }
-}
+
+    if (selector.length) {
+        return selector;
+    }
+};
 
 
-Promo.prototype.get_sphinx_rtd_theme_menu = function () {
+Promo.prototype.get_sphinx_rtd_theme_promo_selector = function () {
+    // Return a jQuery selector where the promo goes on the RTD theme
     var self = this,
-        nav_side = $('nav.wy-nav-side > div.wy-side-scroll');
+        selector;
 
-    if (nav_side.length) {
-        return nav_side;
+    if (self.display_type === constants.PROMO_TYPES.FOOTER) {
+        selector = $('<div />')
+            .attr('class', 'rtd-pro-footer-wrapper')
+            .insertBefore('footer hr');
+        $('<hr />').insertBefore(selector);
+    } else {
+        selector = $('nav.wy-nav-side > div.wy-side-scroll');
     }
-}
+
+    if (selector.length) {
+        return selector;
+    }
+};
 
 // Position promo
 Promo.prototype.display = function () {
@@ -121,10 +151,10 @@ Promo.prototype.display = function () {
     if (promo) {
         promo.show();
     }
-}
+};
 
 Promo.prototype.disable = function () {
-}
+};
 
 // Variant factory method
 Promo.from_variants = function (variants) {