68 (#35)

.gitignore

@@ -1,4 +1,3 @@
 _build
 chrome_settings_overrides.rst
-conf.py
 overlay/*.rst

_extensions/versionwarning/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+name = 'versionwarning'
+version = '1.1.2.dev0'

_extensions/versionwarning/_static/js/versionwarning.js

@@ -0,0 +1,140 @@
+function injectVersionWarningBanner(running_version, highest_version, config, versions) {
+    console.debug("injectVersionWarningBanner");
+    var current_url = window.location.pathname;
+    var isIndex = current_url.endsWith(running_version.slug + "/") || current_url.endsWith(running_version.slug + "/index.html");
+
+    var others = [];
+    $.each(versions, function (i, version) {
+        if (version.slug != running_version.slug && version.slug != highest_version.slug) {
+            let label = version.slug;
+            if (label == "latest") {
+                label = "Latest"
+            }
+            others.push("<a href='" + current_url.replace(running_version.slug, version.slug) + "'>" +label + "</a>");
+        }
+    });
+    let other = others.pop();
+    let first = others.join(", ");
+    if (first) {
+        other = first + " & " + other;
+    }
+
+    let msg = (config.banner.older_indexmessage && isIndex) 
+                        ? config.banner.older_indexmessage
+                        : config.banner.older_message;
+    let title =  config.banner.older_title;
+    let type = config.banner.older_type
+    if (running_version.slug == "latest") {
+        msg = (config.banner.latest_indexmessage && isIndex) 
+                        ? config.banner.latest_indexmessage
+                        : config.banner.latest_message;
+        title =  config.banner.latest_title;
+        type = config.banner.latest_type
+    } else if (running_version.slug == highest_version.slug) {
+        msg = (config.banner.current_indexmessage && isIndex) 
+                        ? config.banner.current_indexmessage
+                        : config.banner.current_message;
+        title =  config.banner.current_title;
+        type = config.banner.current_type
+    } 
+
+    if (msg) {
+        var warning = $(
+            config.banner.html
+                .replace("{message}", msg)
+                .replace("{id_div}", config.banner.id_div)
+                .replace("{banner_title}", title)
+                .replace("{admonition_type}", type)
+                .replace("{newest}",  '<a href="' + current_url.replace(running_version.slug, highest_version.slug) + '">' + highest_version.slug + '</a>')
+                .replace("{this}", running_version.slug)
+                .replace("{other}", other)
+        );
+
+        var body = $(config.banner.body_selector);
+        body.prepend(warning);
+    }
+}
+
+function getHighestVersion(versions) {
+    console.debug("getHighestVersion");
+    var highest_version;
+
+    $.each(versions, function (i, version) {
+        if (isNaN(version.slug)) {
+            // Skip versions that are not numbers
+        }
+        else if (!highest_version) {
+            highest_version = version;
+        }
+        else if (version.slug > highest_version.slug) {
+            highest_version = version;
+        }
+    });
+    return highest_version;
+}
+
+
+function checkVersion(config) {
+    console.debug("checkVersion");
+    var running_version = config.version;
+    console.debug("Running version: " + running_version.slug);
+
+    var get_data = {
+        project__slug: config.project.slug,
+        active: "true"
+        // format: "jsonp",
+    };
+
+    $.ajax({
+        url: config.meta.api_url + "version/",
+        // Used when working locally for development
+        // crossDomain: true,
+        // xhrFields: {
+        //     withCredentials: true,
+        // },
+        // dataType: "jsonp",
+        data: get_data,
+        success: function (versions) {
+            // TODO: fetch more versions if there are more pages (next)
+            highest_version = getHighestVersion(versions["results"]);
+            if (true
+//                semver.valid(semver.coerce(running_version.slug)) && semver.valid(semver.coerce(highest_version.slug)) &&
+//                semver.lt(semver.coerce(running_version.slug), semver.coerce(highest_version.slug))
+            ) {
+                console.debug("Highest version: " + highest_version.slug);
+                injectVersionWarningBanner(running_version, highest_version, config, versions["results"]);
+            }
+        },
+        error: function () {
+            console.error("Error loading Read the Docs active versions.");
+        }
+    });
+}
+
+function init() {
+    console.debug("init");
+    // get the base_url so we can get the versionwarning-data.json from
+    // any page.
+    var base_url = $('script[src*=versionwarning]').attr('src');
+    base_url = base_url.replace('versionwarning.js', '');
+    $.ajax({
+        url: base_url + "../../_static/data/versionwarning-data.json",
+        success: function(config) {
+            // Check if there is already a banner added statically
+            var banner = document.getElementById(config.banner.id_div);
+            if (banner) {
+                console.debug("There is already a banner added. No checking versions.")
+            } else {
+                checkVersion(config);
+            }
+        },
+        error: function() {
+            console.error("Error loading versionwarning-data.json");
+        },
+    })
+}
+
+
+$(document).ready(function () {
+    init();
+});

_extensions/versionwarning/extension.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+import os
+import sphinx
+from versionwarning import version
+from .signals import generate_versionwarning_data_json
+
+
+def setup(app):
+    default_message = 'You are not reading the most up to date version of this documentation. {newest} is the newest version.'
+
+    banner_html = '''
+    <div id="{id_div}" class="admonition {admonition_type}">
+        <p class="first admonition-title">{banner_title}</p>
+            <p class="last">
+                {message}
+            </p>
+    </div>'''
+
+    app.add_config_value('versionwarning_older_message', default_message, 'html')
+    app.add_config_value('versionwarning_older_indexmessage', '', 'html')
+    app.add_config_value('versionwarning_older_title', 'Warning', 'html')
+    app.add_config_value('versionwarning_older_type', 'warning', 'html')
+
+    app.add_config_value('versionwarning_current_message', '', 'html')
+    app.add_config_value('versionwarning_current_indexmessage', '', 'html')
+    app.add_config_value('versionwarning_current_title', 'Warning', 'html')
+    app.add_config_value('versionwarning_current_type', 'warning', 'html')
+
+    app.add_config_value('versionwarning_latest_message', '', 'html')
+    app.add_config_value('versionwarning_latest_indexmessage', '', 'html')
+    app.add_config_value('versionwarning_latest_title', 'Warning', 'html')
+    app.add_config_value('versionwarning_latest_type', 'warning', 'html')
+
+    app.add_config_value('versionwarning_api_url', 'https://readthedocs.org/api/v2/', 'html')
+    app.add_config_value('versionwarning_banner_html', banner_html, 'html')
+    app.add_config_value('versionwarning_banner_id_div', 'version-warning-banner', 'html')
+    app.add_config_value('versionwarning_body_selector', 'div.body', 'html')
+    app.add_config_value('versionwarning_project_slug', os.environ.get('READTHEDOCS_PROJECT', None), 'html')
+    app.add_config_value('versionwarning_project_version', os.environ.get('READTHEDOCS_VERSION', None), 'html')
+
+    if sphinx.version_info >= (1, 8):
+        # ``config-initied`` requires Sphinx >= 1.8
+        app.connect('config-inited', generate_versionwarning_data_json)
+
+        # ``add_js_file`` requires Sphinx >= 1.8
+        app.add_js_file('js/versionwarning.js')
+    else:
+        app.connect('builder-inited', generate_versionwarning_data_json)
+        app.add_javascript('js/versionwarning.js')
+
+    return {
+        'version': version,
+        'env_version': 1,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

_extensions/versionwarning/signals.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+
+import json
+import os
+
+
+STATIC_PATH = os.path.join(os.path.dirname(__file__), '_static')
+JSON_DATA_FILENAME = 'versionwarning-data.json'
+
+
+def generate_versionwarning_data_json(app, config=None, **kwargs):
+    """
+    Generate the ``versionwarning-data.json`` file.
+
+    This file is included in the output and read by the AJAX request when
+    accessing to the documentation and used to compare the live versions with
+    the curent one.
+
+    Besides, this file contains meta data about the project, the API to use and
+    the banner itself.
+    """
+
+    # In Sphinx >= 1.8 we use ``config-initied`` signal which comes with the
+    # ``config`` object and in Sphinx < 1.8 we use ``builder-initied`` signal
+    # that doesn't have the ``config`` object and we take it from the ``app``
+    config = config or kwargs.pop('config', None)
+    if config is None:
+        config = app.config
+
+    #if config.versionwarning_project_version in config.versionwarning_messages:
+    #    custom = True
+    #    message = config.versionwarning_messages.get(config.versionwarning_project_version)
+    #else:
+    #    custom = False
+    #    message = config.versionwarning_default_message
+
+    #banner_html = config.versionwarning_banner_html.format(
+    #    id_div=config.versionwarning_banner_id_div,
+    #    banner_title=config.versionwarning_banner_title,
+    #    message=message.format(
+    #        **{config.versionwarning_message_placeholder: '<a href="#"></a>'},
+    #    ),
+    #    admonition_type=config.versionwarning_admonition_type,
+    #)
+
+    data = json.dumps({
+        'meta': {
+            'api_url': config.versionwarning_api_url,
+        },
+        'banner': {
+            'html': config.versionwarning_banner_html,
+            'id_div': config.versionwarning_banner_id_div,
+            'body_selector': config.versionwarning_body_selector,
+            'older_message': config.versionwarning_older_message,
+            'older_indexmessage': config.versionwarning_older_indexmessage,
+            'older_title': config.versionwarning_older_title,
+            'older_type': config.versionwarning_older_type,
+            'current_message': config.versionwarning_current_message,
+            'current_indexmessage': config.versionwarning_current_indexmessage,
+            'current_title': config.versionwarning_current_title,
+            'current_type': config.versionwarning_current_type,
+            'latest_message': config.versionwarning_latest_message,
+            'latest_indexmessage': config.versionwarning_latest_indexmessage,
+            'latest_title': config.versionwarning_latest_title,
+            'latest_type': config.versionwarning_latest_type,
+        },
+        'project': {
+            'slug': config.versionwarning_project_slug,
+        },
+        'version': {
+            'slug': config.versionwarning_project_version,
+        },
+    }, indent=4)
+
+    data_path = os.path.join(STATIC_PATH, 'data')
+    if not os.path.exists(data_path):
+        os.mkdir(data_path)
+
+    with open(os.path.join(data_path, JSON_DATA_FILENAME), 'w') as f:
+        f.write(data)
+
+    # Add the path where ``versionwarning-data.json`` file and
+    # ``versionwarning.js`` are saved
+    config.html_static_path.append(STATIC_PATH)

_static/theme_overrides.css

@@ -0,0 +1,19 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+  .wy-table-responsive table td {
+    /* !important prevents the common CSS stylesheets from
+       overriding this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+  }
+
+  .wy-table-responsive table p {
+    line-height: 22px !important;
+	font-size: 0.91rem !important;
+  }
+
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
+
+}

conf.py

@@ -0,0 +1,50 @@
+import sys, os
+
+# local extension folder
+sys.path.append(os.path.abspath('_extensions'))
+
+project = u'Thunderbird WebExtension APIs'
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', 'overlay']
+html_theme = 'sphinx_rtd_theme'
+
+html_theme_options = {
+    # Toc options
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Configure headers
+versionwarning_body_selector = 'div[itemprop="articleBody"]'
+
+versionwarning_latest_type = 'tip'
+versionwarning_latest_title = 'Note'   
+versionwarning_latest_message = 'This is the API documentation for pre-release versions of Thunderbird. See version {newest} for the current ESR of Thunderbird.'
+
+versionwarning_current_type = 'tip'
+versionwarning_current_title = 'Note'   
+versionwarning_current_indexmessage = 'This is the API documentation for the current ESR of Thunderbird, version {this}. Other available versions are: {other}'
+
+versionwarning_older_type = 'warning'
+versionwarning_older_title = 'Warning'   
+versionwarning_older_message = 'This is the API documentation for Thunderbird {this}. See version {newest} for the current ESR of Thunderbird.'
+
+
+extensions = [
+    # ... other extensions here
+    'versionwarning.extension',
+    #'sphinx_toolbox.confval',
+]
+
+def setup(app):
+   #app.add_javascript("custom.js")
+   app.add_stylesheet('theme_overrides.css')

how-to/eventListeners.rst

@@ -0,0 +1,23 @@
+==========================
+Working with WebExtension Events
+==========================
+
+WebExtensions can react on events by attaching a listener. Consider the :ref:`menus.onClicked` event of the menus API:
+
+.. code-block:: javascript
+
+  async function menuListener(info, tab) {
+    ...
+    // do something with the info and tab parameters received from the event
+  }
+  
+  messenger.menus.onClicked.addListener(menuListener);
+  
+Using a more modern syntax:
+
+.. code-block:: javascript
+ 
+  messenger.menus.onClicked.addListener(async (info, tab) => {
+    // do something with the info and tab parameters received from the event
+	...
+  });