Sidebar updates

assets/html/documenter.css

@@ -144,35 +144,62 @@ nav.toc .logo {
 
 nav.toc h1 {
     text-align: center;
+    margin-top: .57em;
+    margin-bottom: 0;
 }
 
-nav.toc input {
+nav.toc select {
     display: block;
     height: 2em;
-    width: 90%;
-    width: calc(100% - 5em);
+    padding: 0 1.6em 0 1em;
+    min-width: 7em;
+    max-width: 90%;
+    max-width: calc(100% - 5em);
     margin: 0 auto;
-    padding: 0 1em;
+    font-size: .83em;
     border: 1px solid #c9c9c9;
     border-radius: 1em;
-    font-size: smaller;
+
+    /* TODO: doesn't seem to be centered on Safari */
+    text-align: center;
+    text-align-last: center;
+
+    appearance: none;
+    -moz-appearance: none;
+    -webkit-appearance: none;
+
+    background: white url("arrow.svg");
+    background-size: 1.155em;
+    background-repeat: no-repeat;
+    background-position: right;
 }
 
-nav.toc select {
+nav.toc select:hover {
+    border: 1px solid #a0a0a0;
+}
+
+nav.toc select option {
+    text-align: center;
+}
+
+nav.toc input {
     display: block;
     height: 2em;
-    width: calc(100% - 3em);
-    margin: 5px auto;
-    font-size: smaller;
-    text-align: center;
+    width: 90%;
+    width: calc(100% - 5em);
+    margin: 1.2em auto;
+    padding: 0 1em;
+    border: 1px solid #c9c9c9;
+    border-radius: 1em;
+    font-size: .83em;
 }
 
 nav.toc > ul * {
     margin: 0;
 }
 
 nav.toc ul {
-    color: #b3b3b3;
+    color: #404040;
     padding: 0;
     list-style: none;
 }
@@ -183,6 +210,7 @@ nav.toc ul .toctext {
 }
 
 nav.toc ul a:hover {
+    color: #fcfcfc;
     background-color: #4e4a4a;
 }
 
@@ -196,7 +224,6 @@ nav.toc ul.internal a:hover {
 }
 
 nav.toc ul.internal {
-    color: gray;
     background-color: #e3e3e3;
     box-shadow: inset -14px 0px 5px -12px rgb(210,210,210);
     list-style: none;

assets/html/documenter.js

@@ -52,14 +52,45 @@ require(['mathjax'], function(MathJax) {
 
 require(['jquery', 'highlight', 'highlight-julia'], function($, hljs) {
     $(document).ready(function() {
+        hljs.initHighlighting();
+    })
+
+})
+
+// update the version selector with info from the siteinfo.js and ../versions.js files
+require(['jquery'], function($) {
+    $(document).ready(function() {
+        var version_selector = $("#version-selector");
+
+        // add the current version to the selector based on siteinfo.js, but only if the selector is empty
+        if (typeof DOCUMENTER_CURRENT_VERSION !== 'undefined' && $('#version-selector > option').length == 0) {
+            var option = $("<option value='#' selected='selected'>" + DOCUMENTER_CURRENT_VERSION + "</option>");
+            version_selector.append(option);
+        }
+
         if (typeof DOC_VERSIONS !== 'undefined') {
-            var version_selector = $("#version-selector");
+            var existing_versions = $('#version-selector > option');
+            var existing_versions_texts = existing_versions.map(function(i,x){return x.text});
             DOC_VERSIONS.forEach(function(each) {
-                var option = $("<option value='" + documenterBaseURL + "/../" + each + "'>" + each + "</option>");
-                version_selector.append(option);
+                var version_url = documenterBaseURL + "/../" + each;
+                var existing_id = $.inArray(each, existing_versions_texts);
+                // if not already in the version selector, add it as a new option,
+                // otherwise update the old option with the URL and enable it
+                if (existing_id == -1) {
+                    var option = $("<option value='" + version_url + "'>" + each + "</option>");
+                    version_selector.append(option);
+                } else {
+                    var option = existing_versions[existing_id];
+                    option.value = version_url;
+                    option.disabled = false;
+                }
             });
         }
-        hljs.initHighlighting();
+
+        // only show the version selector if the selector has been populated
+        if ($('#version-selector > option').length > 0) {
+            version_selector.css("visibility", "visible");
+        }
     })
 
 })

src/Documenter.jl

@@ -149,6 +149,11 @@ For example if you are using GitLab.com, you could use
 makedocs(repo = \"https://gitlab.com/user/project/blob/{commit}{path}#L{line}\")
 ```
 
+**`version`** specifies the version string of the current version which will be the
+selected option in the version selector. If this is left empty (default) the version
+selector will be hidden. The special value `git-commit` sets the value in the output to
+`git:{commit}`, where `{commit}` is the first few characters of the current commit hash.
+
 # See Also
 
 A guide detailing how to document a package using Documenter's [`makedocs`](@ref) is provided
@@ -434,15 +439,19 @@ function deploydocs(;
                         # Copy docs to `latest`, or `stable`, `<release>`, and `<version>` directories.
                         if isempty(travis_tag)
                             cp(target_dir, latest_dir; remove_destination = true)
+                            Writers.HTMLWriter.generate_siteinfo_file(latest_dir, "latest")
                         else
                             cp(target_dir, stable_dir; remove_destination = true)
+                            Writers.HTMLWriter.generate_siteinfo_file(stable_dir, "stable")
                             cp(target_dir, tagged_dir; remove_destination = true)
+                            Writers.HTMLWriter.generate_siteinfo_file(tagged_dir, travis_tag)
                             # Build a `release-*.*` folder as well when the travis tag is
                             # valid, which it *should* always be anyway.
                             if ismatch(Base.VERSION_REGEX, travis_tag)
                                 local version = VersionNumber(travis_tag)
                                 local release = "release-$(version.major).$(version.minor)"
                                 cp(target_dir, joinpath(dirname, release); remove_destination = true)
+                                Writers.HTMLWriter.generate_siteinfo_file(joinpath(dirname, release), release)
                             end
                         end
 

src/Documents.jl

@@ -195,6 +195,7 @@ immutable User
     sitename:: Compat.String
     authors :: Compat.String
     analytics::Compat.String
+    version :: Compat.String # version string used in the version selector by default
 end
 
 """
@@ -244,13 +245,18 @@ function Document(;
         sitename :: AbstractString   = "",
         authors  :: AbstractString   = "",
         analytics :: AbstractString = "",
+        version :: AbstractString = "",
         others...
     )
     Utilities.check_kwargs(others)
 
     local fmt = Formats.fmt(format)
     @assert !isempty(fmt) "No formats provided."
 
+    if version == "git-commit"
+        version = "git:$(Utilities.get_commit_short(root))"
+    end
+
     user = User(
         root,
         source,
@@ -268,6 +274,7 @@ function Document(;
         sitename,
         authors,
         analytics,
+        version,
     )
     internal = Internal(
         Utilities.assetsdir(),

src/Utilities/Utilities.jl

@@ -4,6 +4,7 @@ Provides a collection of utility functions and types that are used in other subm
 module Utilities
 
 using Base.Meta, Compat
+using DocStringExtensions
 
 # Logging output.
 
@@ -505,6 +506,18 @@ function getremote(dir::AbstractString)
     end
 end
 
+"""
+$(SIGNATURES)
+
+Returns the first 5 characters of the current git commit hash of the directory `dir`.
+"""
+function get_commit_short(dir)
+    commit = cd(dir) do
+        readchomp(`git rev-parse HEAD`)
+    end
+    (length(commit) > 5) ? commit[1:5] : commit
+end
+
 function inbase(m::Module)
     if m ≡ Base
         true

src/Writers/HTMLWriter.jl

@@ -89,6 +89,7 @@ function render(doc::Documents.Document)
     ctx.search_index_js = "search_index.js"
 
     ctx.documenter_css = copy_asset("documenter.css", doc)
+    copy_asset("arrow.svg", doc)
 
     let logo = joinpath("assets", "logo.png")
         if isfile(joinpath(doc.user.build, logo))
@@ -196,6 +197,7 @@ function render_head(ctx, navnode)
             Symbol("data-main") => relhref(src, ctx.documenter_js)
         ],
 
+        script[:src => relhref(src, "siteinfo.js")],
         script[:src => relhref(src, "../versions.js")],
 
         # Custom user-provided assets.
@@ -281,18 +283,21 @@ function render_navmenu(ctx, navnode)
         )
     end
     push!(navmenu.nodes, h1(ctx.doc.user.sitename))
-    push!(navmenu.nodes,
-        form[".search", :action => relhref(src, "search.html")](
-            select[
-                "#version-selector",
-                :onChange => "window.location.href=this.value",
-            ](
+    let version_selector = select["#version-selector", :onChange => "window.location.href=this.value"]()
+        if isempty(ctx.doc.user.version)
+            push!(version_selector.attributes, :style => "visibility: hidden")
+        else
+            push!(version_selector.nodes,
                 option[
                     :value => "#",
                     :selected => "selected",
-                    :disabled => "disabled",
-                ]("Version"),
-            ),
+                ](ctx.doc.user.version)
+            )
+        end
+        push!(navmenu.nodes, version_selector)
+    end
+    push!(navmenu.nodes,
+        form[".search", :action => relhref(src, "search.html")](
             input[
                 "#search-query",
                 :name => "q",
@@ -424,6 +429,12 @@ function generate_version_file(dir::AbstractString)
     end
 end
 
+function generate_siteinfo_file(dir::AbstractString, version::AbstractString)
+    open(joinpath(dir, "siteinfo.js"), "w") do buf
+        println(buf, "var DOCUMENTER_CURRENT_VERSION = \"$(version)\";")
+    end
+end
+
 ## domify(...)
 # ------------