DOCS-454 make docs version aware and add version navigator

bin/makefile.meta

@@ -0,0 +1,9 @@
+manual-branch = $(shell bin/mongodb_docs_meta.py manual)
+current-branch := $(shell bin/mongodb_docs_meta.py branch)
+last-commit := $(shell bin/mongodb_docs_meta.py commit)
+
+ifeq ($(current-branch),$(manual-branch))
+     current-if-not-manual = manual
+else
+     current-if-not-manual = $(current-branch)
+endif

bin/mongodb_docs_meta.py

@@ -3,8 +3,12 @@
 import datetime
 import re
 import subprocess
+import argparse
 
 MANUAL_BRANCH = 'master'
+PUBLISHED_VERSIONS = [ '2.4', '2.2' ]
+STABLE_RELEASE = PUBLISHED_VERSIONS[0]
+UPCOMING_RELEASE = None
 
 def shell_value( args ):
     if isinstance( args , str ):
@@ -16,7 +20,7 @@ def shell_value( args ):
     return value
 
 def get_manual_path():
-    branch = shell_value('git symbolic-ref HEAD').split('/')[2]
+    branch = get_branch()
 
     if branch == MANUAL_BRANCH:
         manual_path = MANUAL_BRANCH
@@ -31,13 +35,52 @@ def get_commit():
 def get_branch():
     return shell_value('git symbolic-ref HEAD').split('/')[2]
 
+def get_versions():
+    o = []
+
+    for version in PUBLISHED_VERSIONS:
+        version_string = str(version)
+        path_name = 'v' + version_string
+
+        if version == STABLE_RELEASE:
+            version_string += ' (stable)'
+        elif version == UPCOMING_RELEASE:
+            version_string += ' (upcoming)'
+
+        version_dict = { 'v': path_name, 't': version_string }
+        o.append(version_dict)
+
+    return o
+
+
 def main():
-    BREAK = "\n"
+    action_list = ['branch', 'commit', 'versions', 'stable', 'all', 'manual']
+    parser = argparse.ArgumentParser('MongoDB Documentation Meta Data Provider')
+    parser.add_argument('action', choices=action_list, nargs='?', default='all')
+
+    action = parser.parse_args().action
+
+    if action == 'all':
+        BREAK = "\n"
 
-    print("MongoDB Manual:" + BREAK +
-          "     Commit: " + meta_commit() + BREAK +
-          "     Branch: " + meta_branch() + BREAK +
-          "     Year: " + str(datetime.date.today().year))
+        print("MongoDB Manual:" + BREAK +
+              "     Commit: " + get_commit() + BREAK +
+              "     Branch: " + get_branch() + BREAK +
+              "     Manual: " + MANUAL_BRANCH + BREAK +
+              "     Versions: " + str(PUBLISHED_VERSIONS) + BREAK +
+              "     Stable: " + str(STABLE_RELEASE) + BREAK +
+              "     Year: " + str(datetime.date.today().year) + BREAK +
+              "     Version UI: " + str(get_versions()))
+    elif action == 'branch':
+        print(get_branch())
+    elif action == 'commit':
+        print(get_commit())
+    elif action == 'stable':
+        print(STABLE_RELEASE)
+    elif action == 'versions':
+        print(PUBLISHED_VERSIONS)
+    elif action == 'manual':
+        print(MANUAL_BRANCH)
 
 if __name__ == '__main__':
     main()

conf.py

@@ -18,6 +18,8 @@
     'commit': mongodb_docs_meta.get_commit(),
     'manual_path': mongodb_docs_meta.get_manual_path(),
     'date': str(datetime.date.today().year),
+    'version_selector': mongodb_docs_meta.get_versions(),
+    'stable': mongodb_docs_meta.STABLE_RELEASE
 }
 
 # -- General configuration ----------------------------------------------------
@@ -41,14 +43,14 @@
 master_doc = 'contents'
 project = u'mongodb-manual'
 copyright = u'2011-' + meta['date'] + ', 10gen, Inc.'
-version = '2.2.3'
-release = version
+version = '2.4'
+release = '2.4.0'
 
 BREAK = '\n'
 rst_epilog = ('.. |branch| replace:: ``' + meta['branch'] + '``' + BREAK +
               '.. |copy| unicode:: U+000A9' + BREAK +
               '.. |year| replace:: ' + meta['date'] + BREAK +
-              '.. |ent-build| replace:: the MongoDB Subscriber Edition' + BREAK + 
+              '.. |ent-build| replace:: the MongoDB Subscriber Edition' + BREAK +
               '.. |hardlink| replace:: http://docs.mongodb.org/' + meta['branch'])
 
 pygments_style = 'sphinx'
@@ -130,6 +132,9 @@
     'jira_project': 'DOCS',
     'google_analytics': 'UA-7301842-8',
     'project': 'manual',
+    'version': version, 
+    'version_selector': meta['version_selector'],
+    'stable': meta['stable'],
 }
 
 html_sidebars = {

makefile

@@ -10,16 +10,6 @@ public-output = $(output)/public
 branch-output = $(output)/$(current-branch)
 public-branch-output = $(public-output)/$(current-branch)
 
-# get current branch & commit; set the branch that  "manual/" points to; + a conditional
-manual-branch = master
-current-branch := $(shell git symbolic-ref HEAD 2>/dev/null | cut -d "/" -f "3" )
-last-commit := $(shell git rev-parse --verify HEAD)
-ifeq ($(current-branch),$(manual-branch))
-current-if-not-manual = manual
-else
-current-if-not-manual = $(current-branch)
-endif
-
 help:
 	@echo "Use 'make <target>', where <target> is a Sphinx target (e.g. 'html', 'latex')"
 	@echo "See 'meta.build.rst' for more on the build. Use the following MongoDB Manual targets:"
@@ -36,6 +26,7 @@ include bin/makefile.content
 include bin/makefile.tables
 include bin/makefile.push
 include bin/makefile.manpages
+include bin/makefile.meta
 
 ############# Meta targets that control the build and publication process. #############
 publish-if-up-to-date:

themes/mongodb/layout.html

@@ -6,7 +6,7 @@
                          (sidebars != []) %}
 {%- set url_root = pathto('', 1) %}
 {%- if not embedded and docstitle %}
-  {%- set titlesuffix = " — "|safe + docstitle|e %}
+  {%- set titlesuffix = " — "|safe + docstitle|e + " " + release|e %}
 {%- else %}
   {%- set titlesuffix = "" %}
 {%- endif %}
@@ -37,10 +37,10 @@
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '{{ url_root }}',
-        VERSION:     '{{ release|e }}',
+        VERSION:     '{{ version|e }}',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '{{ '' if no_search_suffix else file_suffix }}',
-        HAS_SOURCE:  {{ has_source|lower }}
+        HAS_SOURCE:  {{ has_source|lower }},
       };
     </script>
     {%- for scriptfile in script_files %}
@@ -81,6 +81,7 @@
     <link rel="shortcut icon" href="http://media.mongodb.org/favicon.ico" />
     <meta name="robots" content="index" />
     <meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
+    <meta name="release" content="{{theme_release}}"/>
 
     {%- if pagename == 'index' %}
     <link rel="canonical" href="http://docs.mongodb.org/{{theme_project}}/" />
@@ -195,5 +196,8 @@
 {%- block jiracollector %}
 {%- include "jiracollector.html" %}
 {%- endblock %}
+{%- block versionnav %}
+{%- include "versionnav.html"%}
+{%- endblock %}
 </body>
 </html>

themes/mongodb/pagenav.html

@@ -1,7 +1,10 @@
 <h3><a href="{{ pathto(master_doc) }}">{{ shorttitle }}</a>
 {% if theme_project != 'about' %}
 <small><a href="{{ pathto('genindex') }}">{{ _('(Index)') }}</a></small>
-{% endif %}
+{% endif -%}
 </h3>
-
+{% if theme_project == 'manual' %}
+{# the following span is replaced by the javascript in versionnav.html #}
+<h4 id="vnd">Version: <span id="vn">{{version}}</span></h4>
+{% endif %}
 {{ toctree(maxdepth=-1) }}

themes/mongodb/static/mongodb-docs.css_t

@@ -831,3 +831,4 @@ div.highlight-powershell pre { background-color: #F5F5F5; }
 div.admonition-example pre { background-color: #FBFBFB; }
 
 li p.first { margin-bottom: 0em; }
+h4#vnd {padding:0;margin:0;line-height:1.5;padding-left:10px;}

themes/mongodb/theme.conf

@@ -12,4 +12,8 @@ repo_name = REPONAME
 jira_project = JIRA
 google_analytics = GACODE
 project = PROJECT
-translations = LANGUAGES
+translations = LANGUAGES
+version = VERSION
+version_selector = VERSION_SELECTOR
+latest = LATEST
+stable = STABLE

themes/mongodb/versionnav.html

@@ -0,0 +1,46 @@
+<script type="text/javascript">
+var versions = {{theme_version_selector}}
+var pagename = '{{pagename}}'
+var stable = 'v{{theme_stable}}'
+
+function vfnav() {
+    if ( pagename=='index' ) {
+        pn = ''
+    }
+    else {
+        pn = pagename
+    }
+
+    v = $(this).children("option:selected").attr('value')
+
+    if ( (v==0) || (v==stable) ) {
+        uri = '/manual/' + pn
+    }
+    else {
+        uri = '/' + v + '/' + pn
+    }
+    window.location.href= uri;
+}
+
+$(document).ready(function(){
+    $("#vn").html(function(){
+        s=$("<select/>");
+        o='<option/>';
+
+        $.each(versions,function(index, version) {
+            if ( version.v==stable ) {
+                dv=true;
+            }
+            $(o,{value:version.v,text: version.t}).appendTo(s);
+        });
+
+        if ( dv==false ) {
+            $(o, {value:0,text:'(stable)'}).appendTo(s);
+        }
+        return(s);
+    });
+
+    $("#vn select").bind('change', vfnav);
+    $('#vn select').val('v{{version|e}}');
+});
+</script>