Exposing even more variables in Jinja context.

Adding more boolean variables to the context. They'll be needed for
future features (e.g. development banner).

Author: Robpol86

README.rst

@@ -47,7 +47,8 @@ Unreleased
 
 Added
     * Exposing Jinja2 context variables: ``scv_is_branch`` ``scv_is_root_ref`` ``scv_is_tag`` ``scv_root_ref_is_branch``
-      ``scv_root_ref_is_tag``
+      ``scv_root_ref_is_tag`` ``scv_is_greatest_tag`` ``scv_is_recent_branch`` ``scv_is_recent_ref``
+      ``scv_is_recent_tag``
 
 Changed
     * Version links point to that version of the current page if it exists there.

docs/themes.rst

@@ -25,6 +25,28 @@ variables are exposed:
 
     A boolean set to True if the current version being built is from a git branch.
 
+.. attribute:: scv_is_greatest_tag
+
+    A boolean set to True if the current version being built is:
+
+    * From a git tag.
+    * A valid semver-formatted name (e.g. v1.2.3).
+    * The highest version number.
+
+.. attribute:: scv_is_recent_branch
+
+    A boolean set to True if the current version being built is a git branch and is the most recent commit out of just
+    git branches.
+
+.. attribute:: scv_is_recent_ref
+
+    A boolean set to True if the current version being built is the most recent git commit (branch or tag).
+
+.. attribute:: scv_is_recent_tag
+
+    A boolean set to True if the current version being built is a git tag and is the most recent commit out of just git
+    tags.
+
 .. attribute:: scv_is_root_ref
 
     A boolean set to True if the current version being built is the :option:`--root-ref`.

sphinxcontrib/versioning/sphinx_.py

@@ -85,6 +85,10 @@ def html_page_context(cls, app, pagename, templatename, context, doctree):
         context['github_version'] = cls.CURRENT_VERSION
         context['html_theme'] = app.config.html_theme
         context['scv_is_branch'] = this_remote['kind'] == 'heads'
+        context['scv_is_greatest_tag'] = this_remote == versions.greatest_tag_remote
+        context['scv_is_recent_branch'] = this_remote == versions.recent_branch_remote
+        context['scv_is_recent_ref'] = this_remote == versions.recent_remote
+        context['scv_is_recent_tag'] = this_remote == versions.recent_tag_remote
         context['scv_is_root_ref'] = this_remote == versions.root_remote
         context['scv_is_tag'] = this_remote['kind'] == 'tags'
         context['scv_root_ref_is_branch'] = versions.root_remote['kind'] == 'heads'

sphinxcontrib/versioning/versions.py

@@ -93,6 +93,10 @@ class Versions(object):
     URLs are just '.' initially. Set after instantiation by another function elsewhere. Will be relative URL path.
 
     :ivar iter remotes: List of dicts for every branch/tag.
+    :ivar dict greatest_tag_remote: Tag with the highest version number if it's a valid semver.
+    :ivar dict recent_branch_remote: Most recently committed branch.
+    :ivar dict recent_remote: Most recently committed branch/tag.
+    :ivar dict recent_tag_remote: Most recently committed tag.
     :ivar dict root_remote: Branch/tag at the root of all HTML docs.
     """
 
@@ -114,6 +118,10 @@ def __init__(self, remotes, sort=None, prioritize=None, invert=False):
             found_docs=tuple(),  # tuple of str
             url='.',  # str
         ) for r in remotes]
+        self.greatest_tag_remote = None
+        self.recent_branch_remote = None
+        self.recent_remote = None
+        self.recent_tag_remote = None
         self.root_remote = None
 
         # Sort one or more times.
@@ -130,6 +138,19 @@ def __init__(self, remotes, sort=None, prioritize=None, invert=False):
         if invert:
             self.remotes.reverse()
 
+        # Get significant remotes.
+        if self.remotes:
+            remotes = self.remotes[:]
+            multi_sort(remotes, ('chrono',))
+            self.recent_remote = remotes[0]
+            self.recent_branch_remote = ([r for r in remotes if r['kind'] != 'tags'] or [None])[0]
+            self.recent_tag_remote = ([r for r in remotes if r['kind'] == 'tags'] or [None])[0]
+            if self.recent_tag_remote:
+                multi_sort(remotes, ('semver',))
+                greatest_tag_remote = [r for r in remotes if r['kind'] == 'tags'][0]
+                if RE_SEMVER.search(greatest_tag_remote['name']):
+                    self.greatest_tag_remote = greatest_tag_remote
+
     def __bool__(self):
         """True if self.remotes is not empty. Python 3.x."""
         return bool(self.remotes)
@@ -209,7 +230,15 @@ def copy(self, sub_depth=0, pagename=None):
                 else:
                     remote_new['url'] = '{}.html'.format(pagename)
 
-            # Handle root_remote.
+            # Handle pinned remotes.
+            if self.greatest_tag_remote == remote_old:
+                new.greatest_tag_remote = remote_new
+            if self.recent_branch_remote == remote_old:
+                new.recent_branch_remote = remote_new
+            if self.recent_remote == remote_old:
+                new.recent_remote = remote_new
+            if self.recent_tag_remote == remote_old:
+                new.recent_tag_remote = remote_new
             if self.root_remote == remote_old:
                 new.root_remote = remote_new
         return new

tests/test_versions.py

@@ -34,6 +34,10 @@ def test_no_sort(remotes):
     assert actual_all == expected_all
     assert actual_branches == expected_branches
     assert actual_tags == expected_tags
+    assert versions.greatest_tag_remote == versions['v10.0.0']
+    assert versions.recent_branch_remote == versions['zh-pages']
+    assert versions.recent_remote == versions['v2.0.0']
+    assert versions.recent_tag_remote == versions['v2.0.0']
 
 
 @pytest.mark.parametrize('sort', ['', 'alpha', 'chrono', 'semver', 'semver,alpha', 'semver,chrono'])