Adding banner message feature.

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

Fixes #13

Author: Robpol86

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/screenshots/sphinx_rtd_theme_banner_dev.png

@@ -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

docs/screenshots/sphinx_rtd_theme_banner_nourl.png

@@ -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,