Adding banner message feature.

Adding CLI options, Sphinx context variables, etc for displaying banner
messages on non-latest versions.

Fixes #13

README.rst

@@ -48,13 +48,20 @@ Unreleased
 ----------
 
 Added
+    * Option to enable warning banner in old/development versions. Similar to Jinja2's documentation.
+    * Command line options: ``--banner-greatest-tag`` ``--banner-recent-tag`` ``--show-banner`` ``--banner-main-ref``
     * Jinja2 context functions: ``vhasdoc()`` ``vpathto()``
+    * Jinja2 context variables: ``scv_show_banner`` ``scv_banner_greatest_tag`` ``scv_banner_main_ref_is_branch``
+      ``scv_banner_main_ref_is_tag`` ``scv_banner_main_version`` ``scv_banner_recent_tag``
 
 Changed
     * Root ref will also be built in its own directory like other versions. All URLs to root ref will point to the one
       in that directory instead of the root. More info: https://github.com/Robpol86/sphinxcontrib-versioning/issues/15
     * Renamed Jinja2 context variable ``scv_is_root_ref`` to ``scv_is_root``.
 
+Fixed
+    * https://github.com/Robpol86/sphinxcontrib-versioning/issues/13
+
 Removed
     * Jinja2 context variables: ``scv_root_ref_is_branch`` ``scv_root_ref_is_tag``
 

docs/banner.rst

@@ -0,0 +1,30 @@
+.. _banner:
+
+==============
+Banner Message
+==============
+
+Banner messages can be displayed at the top of every document informing users that they are currently viewing either old
+or the development version of the project's documentation, with the exception of the :option:`--banner-main-ref`. This
+feature is inspired by banner on the `Jinja2 documentation <http://jinja.pocoo.org/docs/dev/>`_.
+
+The banner feature is disabled by default. It can be enabled with the :option:`--show-banner` setting.
+
+.. figure:: screenshots/sphinx_rtd_theme_banner_dev.png
+    :target: _images/sphinx_rtd_theme_banner_dev.png
+
+    The message displayed when users are viewing docs from a branch and the :option:`--banner-main-ref` is a tag. The
+    entire banner is a link that sends users to the latest version of the current page if it exists there.
+
+.. figure:: screenshots/sphinx_rtd_theme_banner_old.png
+    :target: _images/sphinx_rtd_theme_banner_old.png
+
+    The message displayed when users are viewing docs from a tag and the :option:`--banner-main-ref` is a tag. Like the
+    message above this one links users to the latest version of the current page.
+
+.. figure:: screenshots/sphinx_rtd_theme_banner_nourl.png
+    :target: _images/sphinx_rtd_theme_banner_nourl.png
+
+    An example of a banner message from a page that does not exist in the :option:`--banner-main-ref` version. Since
+    there is no page to link to this is just text informing the user that they're viewing the development version of the
+    docs.

docs/conf.py

@@ -37,6 +37,7 @@
 googleanalytics_id = 'UA-82627369-1'
 
 # SCVersioning.
-scv_greatest_tag = True
+scv_banner_greatest_tag = True
 scv_grm_exclude = ('.gitignore', '.nojekyll', 'README.rst')
+scv_show_banner = True
 scv_sort = ('semver', 'time')

docs/context.rst

@@ -84,6 +84,36 @@ Functions
             Go to <a href="{{ vpathto('master') }}">master</a> for the latest docs.
         {% endif %}
 
+Banner Variables
+================
+
+These variables are exposed in the Jinja2 context to facilitate displaying the banner message and deciding which message
+to display.
+
+.. attribute:: scv_banner_greatest_tag
+
+    A boolean set to True if :option:`--banner-greatest-tag` is used.
+
+.. attribute:: scv_banner_main_ref_is_branch
+
+    A boolean set to True if the banner main ref is a branch.
+
+.. attribute:: scv_banner_main_ref_is_tag
+
+    A boolean set to True if the banner main ref is a tag.
+
+.. attribute:: scv_banner_main_version
+
+    A string, the value of :option:`--banner-main-ref`.
+
+.. attribute:: scv_banner_recent_tag
+
+    A boolean set to True if :option:`--banner-recent-tag` is used.
+
+.. attribute:: scv_show_banner
+
+    A boolean set to True if :option:`--show-banner` is used.
+
 Other Variables
 ===============
 

docs/index.rst

@@ -39,6 +39,7 @@ Project Links
 
     install
     tutorial
+    banner
     settings
     context
     themes

docs/settings.rst

@@ -124,6 +124,52 @@ Options
 
 These options are available for the build sub command:
 
+.. option:: -a, --banner-greatest-tag, scv_banner_greatest_tag
+
+    Override banner-main-ref to be the tag with the highest version number. If no tags have docs then this option is
+    ignored and :option:`--banner-main-ref` is used.
+
+    This setting may also be specified in your conf.py file. It must be a boolean:
+
+    .. code-block:: python
+
+        scv_banner_greatest_tag = True
+
+.. option:: -A, --banner-recent-tag, scv_banner_recent_tag
+
+    Override banner-main-ref to be the most recent committed tag. If no tags have docs then this option is ignored and
+    :option:`--banner-main-ref` is used.
+
+    This setting may also be specified in your conf.py file. It must be a boolean:
+
+    .. code-block:: python
+
+        scv_banner_recent_tag = True
+
+.. option:: -b, --show-banner, scv_show_banner
+
+    Show a warning banner. Enables the :ref:`banner` feature.
+
+    This setting may also be specified in your conf.py file. It must be a boolean:
+
+    .. code-block:: python
+
+        scv_show_banner = True
+
+.. option:: -B <ref>, --banner-main-ref <ref>, scv_banner_main_ref
+
+    The branch/tag considered to be the latest/current version. The banner will not be displayed in this ref, only in
+    all others. Default is **master**.
+
+    If the banner-main-ref does not exist or does not have docs the banner will be disabled completely in all versions.
+    Docs will continue to be built.
+
+    This setting may also be specified in your conf.py file. It must be a string:
+
+    .. code-block:: python
+
+        scv_banner_main_ref = 'feature_branch'
+
 .. option:: -i, --invert, scv_invert
 
     Invert the order of branches/tags displayed in the sidebars in generated HTML documents. The default order is

setup.py

@@ -100,7 +100,12 @@ def run(cls):
     license=LICENSE,
     long_description=readme(),
     name=NAME,
-    package_data={'': [os.path.join('_templates', 'versions.html')]},
+    package_data={'': [
+        os.path.join('_static', 'banner.css'),
+        os.path.join('_templates', 'banner.html'),
+        os.path.join('_templates', 'layout.html'),
+        os.path.join('_templates', 'versions.html'),
+    ]},
     packages=['sphinxcontrib', os.path.join('sphinxcontrib', 'versioning')],
     url='https://github.com/Robpol86/' + NAME,
     version=VERSION,

sphinxcontrib/versioning/__main__.py

@@ -181,6 +181,13 @@ def build_options(func):
     :return: The wrapped function.
     :rtype: function
     """
+    func = click.option('-a', '--banner-greatest-tag', is_flag=True,
+                        help='Override banner-main-ref to be the tag with the highest version number.')(func)
+    func = click.option('-A', '--banner-recent-tag', is_flag=True,
+                        help='Override banner-main-ref to be the most recent committed tag.')(func)
+    func = click.option('-b', '--show-banner', help='Show a warning banner.', is_flag=True)(func)
+    func = click.option('-B', '--banner-main-ref',
+                        help="Don't show banner on this ref and point banner URLs to this ref. Default master.")(func)
     func = click.option('-i', '--invert', help='Invert/reverse order of versions.', is_flag=True)(func)
     func = click.option('-p', '--priority', type=click.Choice(('branches', 'tags')),
                         help="Group these kinds of versions at the top (for themes that don't separate them).")(func)
@@ -200,6 +207,33 @@ def build_options(func):
     return func
 
 
+def override_root_main_ref(config, remotes, banner):
+    """Override root_ref or banner_main_ref with tags in config if user requested.
+
+    :param sphinxcontrib.versioning.lib.Config config: Runtime configuration.
+    :param iter remotes: List of dicts from Versions.remotes.
+    :param bool banner: Evaluate banner main ref instead of root ref.
+
+    :return: If root/main ref exists.
+    :rtype: bool
+    """
+    log = logging.getLogger(__name__)
+    greatest_tag = config.banner_greatest_tag if banner else config.greatest_tag
+    recent_tag = config.banner_recent_tag if banner else config.recent_tag
+
+    if greatest_tag or recent_tag:
+        candidates = [r for r in remotes if r['kind'] == 'tags']
+        if candidates:
+            multi_sort(candidates, ['semver' if greatest_tag else 'time'])
+            config.update({'banner_main_ref' if banner else 'root_ref': candidates[0]['name']}, overwrite=True)
+        else:
+            flag = '--banner-main-ref' if banner else '--root-ref'
+            log.warning('No git tags with docs found in remote. Falling back to %s value.', flag)
+
+    ref = config.banner_main_ref if banner else config.root_ref
+    return ref in [r['name'] for r in remotes]
+
+
 @cli.command(cls=ClickCommand)
 @build_options
 @click.argument('REL_SOURCE', nargs=-1, required=True)
@@ -249,18 +283,22 @@ def build(config, rel_source, destination, **options):
     )
 
     # Get root ref.
-    if config.greatest_tag or config.recent_tag:
-        candidates = [r for r in versions.remotes if r['kind'] == 'tags']
-        if candidates:
-            multi_sort(candidates, ['semver' if config.greatest_tag else 'time'])
-            config.update(dict(root_ref=candidates[0]['name']), overwrite=True)
-        else:
-            log.warning('No git tags with docs found in remote. Falling back to --root-ref value.')
-    if config.root_ref not in [r[1] for r in remotes]:
+    if not override_root_main_ref(config, versions.remotes, False):
         log.error('Root ref %s not found in: %s', config.root_ref, ' '.join(r[1] for r in remotes))
         raise HandledError
     log.info('Root ref is: %s', config.root_ref)
 
+    # Get banner main ref.
+    if not config.show_banner:
+        config.update(dict(banner_greatest_tag=False, banner_main_ref=None, banner_recent_tag=False), overwrite=True)
+    elif not override_root_main_ref(config, versions.remotes, True):
+        log.warning('Banner main ref %s not found in: %s', config.banner_main_ref, ' '.join(r[1] for r in remotes))
+        log.warning('Disabling banner.')
+        config.update(dict(banner_greatest_tag=False, banner_main_ref=None, banner_recent_tag=False, show_banner=False),
+                      overwrite=True)
+    else:
+        log.info('Banner main ref is: %s', config.banner_main_ref)
+
     # Pre-build.
     log.info("Pre-running Sphinx to collect versions' master_doc and other info.")
     exported_root = pre_build(config.git_root, versions)

sphinxcontrib/versioning/_static/banner.css

@@ -0,0 +1,41 @@
+.scv-banner {
+    padding: 3px;
+    border-radius: 2px;
+    font-size: 80%;
+    text-align: center;
+    color: white;
+    background: #d40 linear-gradient(-45deg,
+        rgba(255, 255, 255, 0.2) 0%,
+        rgba(255, 255, 255, 0.2) 25%,
+        transparent 25%,
+        transparent 50%,
+        rgba(255, 255, 255, 0.2) 50%,
+        rgba(255, 255, 255, 0.2) 75%,
+        transparent 75%,
+        transparent
+    );
+    background-size: 28px 28px;
+}
+.scv-banner > a {
+    color: white;
+}
+
+
+.scv-sphinx_rtd_theme {
+    background-color: #2980B9;
+}
+
+
+.scv-bizstyle {
+    background-color: #336699;
+}
+
+
+.scv-classic {
+    text-align: center !important;
+}
+
+
+.scv-traditional {
+    text-align: center !important;
+}

sphinxcontrib/versioning/_templates/banner.html

@@ -0,0 +1,31 @@
+{# Set banner color via CSS. #}
+{%- set banner_classes = 'scv-banner' %}
+{%- if html_theme in ('sphinx_rtd_theme', 'bizstyle', 'classic', 'traditional') %}
+    {%- set banner_classes = banner_classes + ' scv-' + html_theme %}
+{%- endif %}
+
+{# Set banner message. #}
+{%- if scv_banner_main_version != current_version %}
+    {# Determine base message. #}
+    {%- if scv_is_branch %}
+        {%- set banner_message = '<b>Warning:</b> This document is for the development version of %s.'|format(project) %}
+    {%- else %}
+        {%- set banner_message = '<b>Warning:</b> This document is for an old version of %s.'|format(project) %}
+    {%- endif %}
+    {# Determine URL of main version. #}
+    {%- if vhasdoc(scv_banner_main_version) %}
+        {%- set banner_message = '<a href="%s">' + banner_message + ' The %s version is %s.</a>' %}
+        {%- if scv_banner_main_ref_is_tag %}
+            {%- set banner_message = banner_message|format(vpathto(scv_banner_main_version), 'latest', scv_banner_main_version) %}
+        {%- else %}
+            {%- set banner_message = banner_message|format(vpathto(scv_banner_main_version), 'main', scv_banner_main_version) %}
+        {%- endif %}
+    {%- endif %}
+{%- endif %}
+
+{# Display banner. #}
+{% block banner %}
+{%- if banner_message %}
+    <p class="{{ banner_classes }}">{{ banner_message }}</p>
+{%- endif %}
+{% endblock %}

sphinxcontrib/versioning/_templates/layout.html

@@ -0,0 +1,8 @@
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{# Prepend banner to body. #}
+{%- set body %}
+    {%- if scv_show_banner %}{%- include "banner.html" %}{% endif %}
+    {%- block body %}{% endblock %}  {# Sphinx overrides body block without calling super(). #}
+{% endset %}

sphinxcontrib/versioning/lib.py

@@ -19,13 +19,17 @@ def __init__(self):
         self._program_state = dict()
 
         # Booleans.
+        self.banner_greatest_tag = False
+        self.banner_recent_tag = False
         self.greatest_tag = False
         self.invert = False
         self.no_colors = False
         self.no_local_conf = False
         self.recent_tag = False
+        self.show_banner = False
 
         # Strings.
+        self.banner_main_ref = 'master'
         self.chdir = None
         self.git_root = None
         self.local_conf = None