Repository: bokeh/bokeh

Issue:
Add prominent banner to old versions of the docs
An example here from Django:

https://docs.djangoproject.com/en/1.7/ref/templates/builtins/

Would suggest something even taller / brighter. Text similar to:

```
This page refers to a past release of Bokeh. For the latest released docs, navigate HERE
```



Discussion:
@bryevdv I would like to work on this task. 

While running `make html` command today to build the documentation I found that there were minor discrepancies which were causing `http://bokehplots.com/theme/css/main.css`  not to load properly. Html pages were looking in this way..
![screenshot from 2016-04-04 23-29-46](https://cloud.githubusercontent.com/assets/5843007/14257837/35d9ead4-fabd-11e5-9469-6aaf0836ba76.png)
To resolve it I made minor changes to `sphinx/source/conf.py` and `sphinx/source/bokeh_theme/layout.html`. Now things work fine. Here are the changes https://github.com/bokeh/bokeh/compare/master...waseem18:master

If it's fine, I can send a PR and start working on this task.

@waseem18 I'm not sure those changes are appropriate. I think the issue is that the docs have to be viewed from an actual server, not a file. You can run `make serve` to automatically launch a server and open a browser to the docs on that local server. 

Thanks for the information @bryevdv .I got it now.

ping @birdsarah who may be helpful on this issue

Sure @bryevdv 

@bryevdv @birdsarah This is how I'm planning to proceed on this task. Please correct me if I'm wrong somewhere.
I will `git checkout` every old tag (version) and will change the `bokeh_theme/layout.html` and the css file `http://bokehplots.com/theme/css/main.css`. Is my approach right?

@waseem18 no, this needs to be automated to be reliable. I would imagine something like: a bit of JS in the master template that checks if the current version (it can be templated with the current version hardcoded when the docs are built) is the same as the version at `en/latest` (@birdsarah can probably chime in about how this might be best accomplished...maybe we save a text new file that the JS can load and compare against under the docs build)

This would work going forward. For older versions, we'd have to check them out, apply a patch to the template, and then re-deploy. That's kind of pain, so we might choose to prune some of the older versions at this time. It's also something that can't be done without the necessary credentials, so it's really outside the scope of this issue. The goal for this issue should be the JS needed to add to the master template, to check versions and insert a banner `div` at the top if needed. 

I don't have anything off the top of my head except to go and look at how the django project does it - all their docs/code are open source on github.

here's the django banner in action:
out-of-date version:
https://docs.djangoproject.com/en/1.7/ref/templates/builtins/
supported version: 
https://docs.djangoproject.com/en/1.9/ref/templates/builtins/

@waseem18 since this task requires credentials to interact with our deployed sites, I have gone ahead and worked on it. Using the following code:

```
  $.get("/en/latest/version.txt", function(data) {
    v = $.trim(data)
    style = "font-family: sans-serif;font-size: 16px;width: 100%;text-align: center;background-color: pink;color: firebrick;padding: 5px;padding-top:12px; padding-bottom:12px;"
    loc = window.location.pathname;
    dev = /^\/en\/dev/
    if (dev.exec(loc)) {
      content = $('<div>The documentation on this page refers to a DEVELOPMENT VERSION. For the latest release, go to <a href="http://bokeh.pydata.org/en/latest/">http://bokeh.pydata.org/en/latest/</a></div>').attr('style', style);
      $('html:first').prepend(content);
    }
    else if (v != "0.11.1") {
      content = $('<div>The documentation on this page refers to a PREVIOUS VERSION. For the latest release, go to <a href="http://bokeh.pydata.org/en/latest/">http://bokeh.pydata.org/en/latest/</a></div>').attr('style', style);
      $('html:first').prepend(content);
    }
  })
```

I get, e.g.

<img width="1219" alt="screen shot 2016-04-26 at 4 06 29 pm" src="https://cloud.githubusercontent.com/assets/1078448/14834211/de0d9bc6-0bc8-11e6-8574-58244b90af24.png">

I have trimmed the set of deployed docs to just what is in the current version dropdown (`0.8.2`, `0.9.3`, `0.10.0` and `0.11.1`), and updated all of them by hand with the above code in some way, to get things "working".

To get this going for real automatically going forward, the above JS needs to be added to `main.js` and the "current" version needs to be templated in as part of the doc build somehow (you can see it hardcoded to `0.11.1` above), and the docs deploy to `latest` needs to also upload `version.txt` next to `index.html`

@birdsarah do you have any immediate thoughts on how best to get the current version in there? Previous sphinx builds added a script like this:

```
   <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.9.3',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
```

but that is now gone in the new site layout. 


Resolving patch:
diff --git a/bokeh/document.py b/bokeh/document.py
--- a/bokeh/document.py
+++ b/bokeh/document.py
@@ -461,7 +461,7 @@ def select(self, selector):
 
         Args:
             selector (JSON-like query dictionary) : you can query by type or by
-            name. e.g. ``{"type": HoverTool}``, ``{"name": "mycircle"}``
+                name, e.g. ``{"type": HoverTool}``, ``{"name": "mycircle"}``
 
         Returns:
             seq[Model]
@@ -480,7 +480,7 @@ def select_one(self, selector):
 
         Args:
             selector (JSON-like query dictionary) : you can query by type or by
-            name. e.g. ``{"type": HoverTool}``, ``{"name": "mycircle"}``
+                name, e.g. ``{"type": HoverTool}``, ``{"name": "mycircle"}``
 
         Returns:
             Model
@@ -499,8 +499,8 @@ def set_select(self, selector, updates):
 
         Args:
             selector (JSON-like query dictionary) : you can query by type or by
-            name. e.g. ``{"type": HoverTool}``, ``{"name": "mycircle"}``
-            updates (dict) :
+                name,i e.g. ``{"type": HoverTool}``, ``{"name": "mycircle"}``
+                updates (dict) :
 
         Returns:
             None
diff --git a/sphinx/fabfile.py b/sphinx/fabfile.py
--- a/sphinx/fabfile.py
+++ b/sphinx/fabfile.py
@@ -43,5 +43,6 @@ def latest(v=None):
         # switch the current symlink to new docs
         run("rm /www/bokeh/en/latest")
         run("ln -s /www/bokeh/en/%s /www/bokeh/en/latest" % v)
+        run("echo %s > /www/bokeh/en/latest/version.txt" % v)
     else:
         raise RuntimeError("We did not detect a %s docs version, please use fab deploy:%s first." % (v, v))
diff --git a/sphinx/source/conf.py b/sphinx/source/conf.py
--- a/sphinx/source/conf.py
+++ b/sphinx/source/conf.py
@@ -128,6 +128,7 @@
     'SITENAME': 'Bokeh Docs',
     'DESCRIPTION': 'Bokeh visualization library, documentation site.',
     'AUTHOR': 'Bokeh contributors',
+    'VERSION': version,
     # Nav
     'NAV': (
         ('About', MAIN_SITE + '/pages/about-bokeh.html'),
@@ -165,7 +166,7 @@
         ('Releases', 'releases/%s' % version),
         ('Developer Guide', 'dev_guide'),
     ),
-    'ALL_VERSIONS': ['0.11.0', '0.11.0', '0.10.0', '0.9.3', '0.8.2'],
+    'ALL_VERSIONS': ['0.11.1', '0.11.0', '0.10.0', '0.9.3', '0.8.2'],
     'css_server': os.environ.get('BOKEH_DOCS_CSS_SERVER', 'bokehplots.com'),
 }
 


Test patch: