Merge pull request #15 from humitos/only-dynamic-banner

Support only dynamic banner via Javascript

Author: humitos

CHANGELOG.rst

@@ -1,3 +1,23 @@
+1.0.0
+-----
+
+:Date: UNRELEASED
+
+  * Remove ability to add the warning banner statically
+
+  * Make the banner more customizable (all the configs are included in the ``json`` file generated and available from Javascript)
+
+  * Rename ``versionwarning_default_admonition_type`` by ``versionwarning_admonition_type``
+
+  * Rename ``versionwarning_body_default_selector`` by ``versionwarning_body_selector``
+
+  * Remove ``versionwarning_body_extra_selector``
+
+  * Refactor the code to avoid potential circular imports
+
+  * Filter Read the Docs versions by ``active=True`` when retrieving versions
+
+
 0.2.0
 -----
 

README.rst

@@ -18,9 +18,9 @@ How it works?
 -------------
 
 When visiting a page in Read the Docs that was built with this extension enabled,
-an AJAX request is done to the Read the Docs servers to retrieve all the versions of the project.
+an AJAX request is done to the Read the Docs servers to retrieve all the **active versions** of the project.
 These versions are compared against the one that we are reading and if it's an old version,
-a red *Warning* banner appears at the top of the page.
+a *Warning* banner appears at the top of the page.
 
 
 Examples
@@ -31,13 +31,11 @@ Examples
 There is a live example living at Read the Docs:
 
 - `latest`_ version doesn't show any kind of warning banner
-- `0.0.1`_ version shows a custom and fixed message added at build time
 - `0.0.2`_ version shows a warning banner saying that 0.0.3 is available (at the time of writing this docs)
 - `0.0.3`_ version doesn't show any banner since it's the latest version (at the time of writing this docs)
 
 
 .. _latest: https://sphinx-version-warning-example.readthedocs.io/en/latest/
-.. _0.0.1: https://sphinx-version-warning-example.readthedocs.io/en/0.0.1/
 .. _0.0.2: https://sphinx-version-warning-example.readthedocs.io/en/0.0.2/
 .. _0.0.3: https://sphinx-version-warning-example.readthedocs.io/en/0.0.3/
 
@@ -57,22 +55,24 @@ Then in your ``conf.py`` you have to add ``versionwarning`` in the ``extensions`
   ]
 
 
-Remember to configure the ``version`` of your Sphinx project since it's the key for this to work properly::
+Remember to configure the ``versionwarning_project_version`` and ``versionwarning_project_slug`` of your Sphinx project since it's the key for this to work properly::
 
-  version = '0.0.1'
+  versionwarning_project_version = '0.0.1'
+  versionwarning_project_slug = 'sphinx-version-warning'
 
 .. warning::
 
-   If ``READTHEDOCS_VERSION`` variable is defined, the extension will use its value.
-   Otherwise, ``versionwarning_project_version`` will be used and if it's not defined, ``version`` as last resource.
+   If you are building your documentation under Read the Docs,
+   ``READTHEDOCS_VERSION`` and ``READTHEDOCS_PROECT`` environment variables will be defined and there is no need to define these variables,
+   unless you want to override the default values.
 
 
 Customization
 -------------
 
 Some customization can be done using the ``conf.py`` file of your Sphinx project:
 
-versionwarning_default_admonition_type (string)
+versionwarning_admonition_type (string)
    type of admonition for the banner (warning, admonition or note)
 
 versionwarning_default_message (string)
@@ -88,7 +88,7 @@ versionwarning_project_slug (string)
    slug of the project under Read the Docs (default to ``READTHEDOCS_PROJECT`` environment variable)
 
 versionwarning_project_version (string)
-   slug of the version for the current documentation (default to ``READTHEDOCS_VERSION`` environment variable or ``version`` variable from ``conf.py``)
+   slug of the version for the current documentation (default to ``READTHEDOCS_VERSION`` environment variable)
 
 versionwarning_api_url (string)
    API URL to retrieve all versions for this project
@@ -99,11 +99,8 @@ versionwarning_banner_html (string)
 versionwarning_banner_id_div (string)
    HTML element ID used for the <div> inject as banner
 
-versionwarning_body_default_selector (string)
-   jQuery selector to find the body element in the page
-
-versionwarning_body_extra_selector (string)
-   jQuery selector to find the body element in the page if ``versionwarning_body_default_selector`` wasn't found
+versionwarning_body_selector (string)
+   jQuery selector to find the body element in the page and *prepend* the banner
 
 
 How to contribute?

package.json

@@ -1,9 +1,9 @@
 {
   "name": "sphinx-version-warning",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "dependencies": {
-    "semver": "^5.5.0",
-    "webpack": "^4.16.3",
-    "webpack-cli": "^3.1.0"
+    "semver": "^5.6.0",
+    "webpack": "^4.22.0",
+    "webpack-cli": "^3.1.2"
   }
 }

setup.py

@@ -24,8 +24,6 @@
         'Operating System :: OS Independent',
     ),
     install_requires=[
-        'munch',
-        'slumber',
         'sphinx',
     ],
 )

versionwarning/__init__.py

@@ -1,56 +1,3 @@
 # -*- coding: utf-8 -*-
-
 name = 'versionwarning'
-version = '0.2.0'
-
-
-def setup(app):
-    import os
-    import sphinx
-    from .signals import process_version_warning_banner, generate_versionwarning_data_json
-
-    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 warning">
-        <p class="first admonition-title">{banner_title}</p>
-            <p class="last">
-                {message}
-            </p>
-    </div>'''.format(
-        id_div='version-warning-banner',
-        banner_title='Warning',
-        message=default_message.format(newest='<a href="#"></a>'),
-    )
-
-    app.add_config_value('versionwarning_message_placeholder', '{newest}', 'html')
-    app.add_config_value('versionwarning_default_admonition_type', 'warning', 'html')
-    app.add_config_value('versionwarning_default_message', default_message, 'html')
-    app.add_config_value('versionwarning_messages', {}, '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_default_selector', 'div.body', 'html')
-    app.add_config_value('versionwarning_body_extra_selector', 'div.document', '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')
-
-    app.connect('doctree-resolved', process_version_warning_banner)
-
-    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,
-    }
+version = '1.0.0'

versionwarning/_static/js/versionwarning.js

@@ -1,6 +1,7 @@
 const semver = require('semver');
 
 function injectVersionWarningBanner(running_version, version, config) {
+    console.debug("injectVersionWarningBanner");
     var version_url = window.location.pathname.replace(running_version.slug, version.slug);
     var warning = $(config.banner.html);
 
@@ -9,15 +10,21 @@ function injectVersionWarningBanner(running_version, version, config) {
       .attr("href", version_url)
       .text(version.slug);
 
-    var body = $(config.banner.body_default_selector);
-    if (!body.length) {
-        body = $(config.banner.body_extra_selector);
-    }
+    var body = $(config.banner.body_selector);
+    body.prepend(warning);
+}
+
+
+function injectCustomWarningBanner(config) {
+    console.debug("injectCustomWarningBanner");
+    var warning = $(config.banner.html);
+    var body = $(config.banner.body_selector);
     body.prepend(warning);
 }
 
 
 function getHighestVersion(versions) {
+    console.debug("getHighestVersion");
     var highest_version;
 
     $.each(versions, function (i, version) {
@@ -38,13 +45,13 @@ function getHighestVersion(versions) {
 
 
 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 is not yet deployed
-        // active: "true",
+        active: "true"
         // format: "jsonp",
     };
 
@@ -74,6 +81,7 @@ function checkVersion(config) {
 }
 
 function init() {
+    console.debug("init");
     $.ajax({
         url: "_static/data/versionwarning-data.json",
         success: function(config) {
@@ -82,6 +90,9 @@ function init() {
             if (banner) {
                 console.debug("There is already a banner added. No checking versions.")
             }
+            else if (config.banner.custom) {
+                injectCustomWarningBanner(config);
+            }
             else {
                 checkVersion(config);
             }