From 13749398e843519ea362d6bcd41fdbba304d947c Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Mon, 16 Jan 2017 20:21:42 +0200 Subject: [PATCH 1/2] Increase contrast of sidebar text Increase the contrast of the text in the sidebar by: - making the text near-black, same as the main body - make the :hover text on dark background light (same as nav.toc background) --- assets/html/documenter.css | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/assets/html/documenter.css b/assets/html/documenter.css index 223d44d0e5..8d44f71f59 100644 --- a/assets/html/documenter.css +++ b/assets/html/documenter.css @@ -172,7 +172,7 @@ nav.toc > ul * { } nav.toc ul { - color: #b3b3b3; + color: #404040; padding: 0; list-style: none; } @@ -183,6 +183,7 @@ nav.toc ul .toctext { } nav.toc ul a:hover { + color: #fcfcfc; background-color: #4e4a4a; } @@ -196,7 +197,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; From 37b3606156a7cf8cf5faf9e5e7621d9f819a404e Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Mon, 6 Feb 2017 10:45:46 +1300 Subject: [PATCH 2/2] Update the version selector Add a version argument to makedocs that will allow specifying the version shown in the selector by default. If it is not specified then the version selector will be empty and have visibility: hidden so that an empty selector wouldn't show up. Using visibility: instead of display: so that the sidebar wouldn't jump when the selector gets enabled. Separate the version selector javascript into a separate requirejs block. Amend the version selector javascript so that existing selector options get checked and updated, if necessary. A siteinfo.js file will now also be generated in the root of the build when being deployed which can be used to determine the current version. Move version selector out of search
tag, making it easier to style and since it is not conceptually related to the search. Update the style of the selector to be uniform across browsers, more in line with the style and more connected to the package name rather than the search box. The SVG arrow is necessary to make the dropdown indicator uniform. --- assets/html/arrow.svg | 63 ++++++++++++++++++++++++++++++++++++++ assets/html/documenter.css | 47 ++++++++++++++++++++++------ assets/html/documenter.js | 39 ++++++++++++++++++++--- src/Documenter.jl | 9 ++++++ src/Documents.jl | 7 +++++ src/Utilities/Utilities.jl | 13 ++++++++ src/Writers/HTMLWriter.jl | 29 ++++++++++++------ 7 files changed, 184 insertions(+), 23 deletions(-) create mode 100644 assets/html/arrow.svg diff --git a/assets/html/arrow.svg b/assets/html/arrow.svg new file mode 100644 index 0000000000..ee2798d3fb --- /dev/null +++ b/assets/html/arrow.svg @@ -0,0 +1,63 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/assets/html/documenter.css b/assets/html/documenter.css index 8d44f71f59..32adebb74d 100644 --- a/assets/html/documenter.css +++ b/assets/html/documenter.css @@ -144,27 +144,54 @@ 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 * { diff --git a/assets/html/documenter.js b/assets/html/documenter.js index c86aec0251..58bc18c0e7 100644 --- a/assets/html/documenter.js +++ b/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 = $(""); + 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 = $(""); - 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 = $(""); + 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"); + } }) }) diff --git a/src/Documenter.jl b/src/Documenter.jl index 7a77caa2e3..3ab95f07db 100644 --- a/src/Documenter.jl +++ b/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`, ``, and `` 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 diff --git a/src/Documents.jl b/src/Documents.jl index 950ae4d472..17f119e4bf 100644 --- a/src/Documents.jl +++ b/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,6 +245,7 @@ function Document(; sitename :: AbstractString = "", authors :: AbstractString = "", analytics :: AbstractString = "", + version :: AbstractString = "", others... ) Utilities.check_kwargs(others) @@ -251,6 +253,10 @@ function Document(; 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(), diff --git a/src/Utilities/Utilities.jl b/src/Utilities/Utilities.jl index 3a3bc95ffc..c4ce0a28b9 100644 --- a/src/Utilities/Utilities.jl +++ b/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 diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index 1642813b1c..2b7f136258 100644 --- a/src/Writers/HTMLWriter.jl +++ b/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(...) # ------------