Merge branch 'master' of github.com:rtfd/readthedocs.org

* 'master' of github.com:rtfd/readthedocs.org:
  Add GLOBAL_PIP_CACHE setting (readthedocs#3299)
  Remove invalid attribute `exception` (readthedocs#3298)
  Update build from database at __exit__ (readthedocs#3292)
  Extra way to check OOM of a command ran inside Docker (readthedocs#3294)
  Add supervisord contrib example (readthedocs#3262)
  Allow promos to be placed in the docs footer (readthedocs#3267)
  Do not convert to bytes the `refresh_token` (readthedocs#3273)

Author: kakulukia

.gitignore

@@ -15,6 +15,7 @@
 .ropeproject/
 _build
 bower_components/
+contrib/supervisord.log
 deploy/.vagrant
 dist/*
 local_settings.py
@@ -43,3 +44,4 @@ private_*
 readthedocs/htmlcov
 tags
 .python-version
+*.pyo

contrib/readme.rst

@@ -0,0 +1,28 @@
+Running Read the Docs via Supervisord
+=====================================
+
+This is the easiest way to start all of the commands you'll need for development
+in an environment relatively close to the production evironment. All you need is
+``supervisord`` and ``redis-server``. Installation of ``redis-server`` is
+outside the scope of this documentation, but once installed, all you need to run
+from ``supervisord`` is::
+
+    pip install supervisord
+    cd contrib/
+    supervisord
+
+This will bring up a web instance for the dashboard, a web instance for
+documentation serving, two celery instances, and redis-server. 
+
+If you already are running redis-server, this will complain about the port
+already being in use, but will still load.
+
+Debugging
+---------
+
+To debug, set trace points like normal, with ``pdb``/``ipdb``. Then you can
+connect to the process by bringing it to the foreground::
+
+    supervisorctl fg main
+
+You'll still see logging to STDERR on the main supervisord process page.

contrib/supervisord.conf

@@ -0,0 +1,42 @@
+[supervisord]
+nodaemon = True
+directory = ../
+loglevel = error
+strip_ansi = False
+environment = PYTHONUNBUFFERED=1,READTHEDOCS_INSTANCE=readthedocs.org
+
+[inet_http_server]
+port = 127.0.0.1:9001
+username = 🍔
+password = 🍟
+
+[supervisorctl]
+username = 🍔
+password = 🍟
+
+[rpcinterface:supervisor]
+supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
+
+[program:redis]
+command = redis-server
+directory = ../
+priority = 0
+startretries = 0
+stderr_logfile = /dev/stderr
+stderr_logfile_maxbytes = 0
+
+[program:main]
+command = python manage.py runserver 8000
+directory = ../
+priority = 100
+stopasgroup = True
+stderr_logfile = /dev/stderr
+stderr_logfile_maxbytes = 0
+
+[program:celery]
+command = celery worker -A readthedocsinc -Q default,celery,web,builder -l DEBUG -c 2
+directory = ../
+priority = 100
+stopasgroup = True
+stderr_logfile = /dev/stderr
+stderr_logfile_maxbytes = 0

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,107 +6,137 @@ 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 () {
     var self = this,
         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;
+    if (typeof(menu) != 'undefined') {
+        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 (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 (nav_side.length) {
-        return nav_side;
+    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 (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 (nav_side.length) {
-        return nav_side;
+    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) {