diff --git a/CHANGELOG.md b/CHANGELOG.md index 37349503f5..b5ff8de904 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,28 @@ ## Version `v0.22.0` +* ![Deprecation][badge-deprecation] ![Enhancement][badge-enhancement] The `assets` and `analytics` arguments to `makedocs` have been deprecated in favor of the corresponding arguments of the `Documenter.HTML` format plugin. ([#953][github-953]) + + **For upgrading:** pass the corresponding arguments with the `Documenter.HTML` plugin instead. E.g. instead of + + ``` + makedocs( + assets = ..., analytics = ..., + ... + ) + ``` + + you should have + + ``` + makedocs( + format = Documenter.HTML(assets = ..., analytics = ...), + ... + ) + ``` + + _**Note:** It is technically possible to specify the same argument twice with different values by passing both variants. In that case the value passed to `makedocs` takes precedence._ + * ![Enhancement][badge-enhancement] Documentation is no longer deployed on Travis CI cron jobs. ([#917][github-917]) * ![Enhancement][badge-enhancement] Log messages from failed `@meta`, `@docs`, `@autodocs`, @@ -15,6 +37,8 @@ output, such as images, from `@example` blocks. All the writers now also handle `text/markdown` output, which is preferred over `text/plain` if available. ([#938][github-938], [#948][github-948]) +* ![Enhancement][badge-enhancement] The HTML output now also supports SVG, WebP, GIF and JPEG logos. ([#953][github-953]) + * ![Bugfix][badge-bugfix] Paths in `include` calls in `@eval`, `@example`, `@repl` and `jldoctest` blocks are now interpreted to be relative `pwd`, which is set to the output directory of the resulting file. ([#941][github-941]) @@ -223,6 +247,7 @@ [github-941]: https://github.com/JuliaDocs/Documenter.jl/pull/941 [github-946]: https://github.com/JuliaDocs/Documenter.jl/pull/946 [github-948]: https://github.com/JuliaDocs/Documenter.jl/pull/948 +[github-953]: https://github.com/JuliaDocs/Documenter.jl/pull/953 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl diff --git a/docs/make.jl b/docs/make.jl index c0db89d0c8..2d101a6128 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,12 +6,12 @@ makedocs( # Use clean URLs, unless built as a "local" build prettyurls = !("local" in ARGS), canonical = "https://juliadocs.github.io/Documenter.jl/stable/", + assets = ["assets/favicon.ico"], + analytics = "UA-89508993-1", ), clean = false, - assets = ["assets/favicon.ico"], sitename = "Documenter.jl", authors = "Michael Hatherly, Morten Piibeleht, and contributors.", - analytics = "UA-89508993-1", linkcheck = !("skiplinks" in ARGS), pages = [ "Home" => "index.md", diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png deleted file mode 100644 index 3c0c8a1be4..0000000000 Binary files a/docs/src/assets/logo.png and /dev/null differ diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg new file mode 100644 index 0000000000..dcc0d3c6f0 --- /dev/null +++ b/docs/src/assets/logo.svg @@ -0,0 +1,154 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + ! + ? + + + + + diff --git a/src/Documenter.jl b/src/Documenter.jl index b9e0844548..dd2be56569 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -194,11 +194,14 @@ function makedocs(components...; debug = false, format = HTML(), html_disable_git::Union{Bool, Nothing} = nothing, # deprecated html_edit_branch::Union{String, Nothing} = nothing, # deprecated html_canonical::Union{String, Nothing} = nothing, # deprecated + assets::Union{Vector{<:AbstractString}, Nothing} = nothing, # deprecated + analytics::Union{<:AbstractString, Nothing} = nothing, # deprecated kwargs...) # html_ keywords deprecation html_keywords = Dict() function html_warn(kw) - Base.depwarn(""" + replace_with = startswith(kw, "html_") ? kw[6:end] : kw + @warn """ The `$kw` keyword argument should now be specified in the `Documenter.HTML()` format specifier. To fix this warning replace ``` @@ -206,9 +209,9 @@ function makedocs(components...; debug = false, format = HTML(), ``` with ``` - format = Documenter.HTML($(kw[6:end]) = ...) + format = Documenter.HTML($(replace_with) = ...) ``` - """, :makedocs) + """ end if html_prettyurls !== nothing html_warn("html_prettyurls") @@ -226,6 +229,14 @@ function makedocs(components...; debug = false, format = HTML(), html_warn("html_canonical") html_keywords[:canonical] = html_canonical end + if assets !== nothing + html_warn("assets") + html_keywords[:assets] = assets + end + if analytics !== nothing + html_warn("analytics") + html_keywords[:analytics] = analytics + end # deprecation of format as Symbols function fmt(f) diff --git a/src/Documents.jl b/src/Documents.jl index 7e80b829b9..624c1d6220 100644 --- a/src/Documents.jl +++ b/src/Documents.jl @@ -197,11 +197,9 @@ struct User strict::Bool # Throw an exception when any warnings are encountered. modules :: Set{Module} # Which modules to check for missing docs? pages :: Vector{Any} # Ordering of document pages specified by the user. - assets :: Vector{String} repo :: String # Template for URL to source code repo sitename:: String authors :: String - analytics::String version :: String # version string used in the version selector by default end @@ -250,11 +248,9 @@ function Document(plugins = nothing; strict::Bool = false, modules :: Utilities.ModVec = Module[], pages :: Vector = Any[], - assets :: Vector = String[], repo :: AbstractString = "", sitename :: AbstractString = "", authors :: AbstractString = "", - analytics :: AbstractString = "", version :: AbstractString = "", others... ) @@ -282,11 +278,9 @@ function Document(plugins = nothing; strict, Utilities.submodules(modules), pages, - assets, repo, sitename, authors, - analytics, version ) internal = Internal( diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index 142988737a..036e7e790d 100644 --- a/src/Writers/HTMLWriter.jl +++ b/src/Writers/HTMLWriter.jl @@ -4,23 +4,19 @@ A module for rendering `Document` objects to HTML. # Keywords [`HTMLWriter`](@ref) uses the following additional keyword arguments that can be passed to -[`Documenter.makedocs`](@ref): `assets`, `sitename`, `analytics`, `authors`, `pages`, -`version`. The behavior of [`HTMLWriter`](@ref) can be further customized by passing -[`Documenter.makedocs`](@ref) a [`HTML`](@ref), which accepts the following keyword -arguments: `prettyurls`, `disable_git`, `edit_branch`, `canonical`. +[`Documenter.makedocs`](@ref): `authors`, `pages`, `sitename`, `version`. +The behavior of [`HTMLWriter`](@ref) can be further customized by setting the `format` +keyword of [`Documenter.makedocs`](@ref) to a [`HTML`](@ref), which accepts the following +keyword arguments: `analytics`, `assets`, `canonical`, `disable_git`, `edit_branch` and +`prettyurls`. **`sitename`** is the site's title displayed in the title bar and at the top of the *navigation menu. This argument is mandatory for [`HTMLWriter`](@ref). **`pages`** defines the hierarchy of the navigation menu. -**`assets`** can be used to include additional assets (JS, CSS, ICO etc. files). See below -for more information. - # Experimental keywords -**`analytics`** can be used specify the Google Analytics tracking ID. - **`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 @@ -41,30 +37,6 @@ then it is intended as the page title. This has two consequences: and in the `` tag, unless specified in the `.pages` option. 2. If the first heading is interpreted as being the page title, it is not displayed in the navigation sidebar. - -# Default and custom assets - -Documenter copies all files under the source directory (e.g. `/docs/src/`) over -to the compiled site. It also copies a set of default assets from `/assets/html/` -to the site's `assets/` directory, unless the user already had a file with the -same name, in which case the user's files overrides the Documenter's file. -This could, in principle, be used for customizing the site's style and scripting. - -The HTML output also links certain custom assets to the generated HTML documents, -specifically a logo and additional javascript files. -The asset files that should be linked must be placed in `assets/`, under the source -directory (e.g `/docs/src/assets`) and must be on the top level (i.e. files in -the subdirectories of `assets/` are not linked). - -For the **logo**, Documenter checks for the existence of `assets/logo.png`. -If that's present, it gets displayed in the navigation bar. - -Additional JS, ICO, and CSS assets can be included in the generated pages using the -`assets` keyword for `makedocs`. `assets` must be a `Vector{String}` and will include -each listed asset in the `<head>` of every page in the order in which they are listed. -The type of the asset (i.e. whether it is going to be included with a `<script>` or a -`<link>` tag) is determined by the file's extension -- either `.js`, `.ico`, or `.css`. -Adding an ICO asset is primarilly useful for setting a custom `favicon`. """ module HTMLWriter @@ -123,19 +95,51 @@ This allows search engines to know which version to send their users to. [See wikipedia for more information](https://en.wikipedia.org/wiki/Canonical_link_element). Default is `nothing`, in which case no canonical link is set. +**`analytics`** can be used specify the Google Analytics tracking ID. + +**`assets`** can be used to include additional assets (JS, CSS, ICO etc. files). See below +for more information. + +# Default and custom assets + +Documenter copies all files under the source directory (e.g. `/docs/src/`) over +to the compiled site. It also copies a set of default assets from `/assets/html/` +to the site's `assets/` directory, unless the user already had a file with the +same name, in which case the user's files overrides the Documenter's file. +This could, in principle, be used for customizing the site's style and scripting. + +The HTML output also links certain custom assets to the generated HTML documents, +specifically a logo and additional javascript files. +The asset files that should be linked must be placed in `assets/`, under the source +directory (e.g `/docs/src/assets`) and must be on the top level (i.e. files in +the subdirectories of `assets/` are not linked). + +For the **logo**, Documenter checks for the existence of `assets/logo.{svg,png,webp,gif,jpg,jpeg}`, +in this order. The first one it finds gets displayed at the top of the navigation sidebar. + +Additional JS, ICO, and CSS assets can be included in the generated pages using the +`assets` keyword for `makedocs`. `assets` must be a `Vector{String}` and will include +each listed asset in the `<head>` of every page in the order in which they are listed. +The type of the asset (i.e. whether it is going to be included with a `<script>` or a +`<link>` tag) is determined by the file's extension -- either `.js`, `.ico`, or `.css`. +Adding an ICO asset is primarilly useful for setting a custom `favicon`. """ struct HTML <: Documenter.Plugin - prettyurls::Bool - disable_git:: Bool - edit_branch:: Union{String, Nothing} - canonical:: Union{String, Nothing} + prettyurls :: Bool + disable_git :: Bool + edit_branch :: Union{String, Nothing} + canonical :: Union{String, Nothing} + assets :: Vector{String} + analytics :: String function HTML(; prettyurls::Bool = true, disable_git::Bool = false, edit_branch::Union{String, Nothing} = "master", - canonical::Union{String, Nothing} = nothing) - new(prettyurls, disable_git, edit_branch, canonical) + canonical::Union{String, Nothing} = nothing, + assets::Vector{String} = String[], + analytics::String = "") + new(prettyurls, disable_git, edit_branch, canonical, assets, analytics) end end @@ -178,9 +182,11 @@ function render(doc::Documents.Document, settings::HTML=HTML()) copy_asset("arrow.svg", doc) - let logo = joinpath("assets", "logo.png") + for logoext in ["svg", "png", "webp", "gif", "jpg", "jpeg"] + logo = joinpath("assets", "logo.$(logoext)") if isfile(joinpath(doc.user.build, logo)) ctx.logo = logo + break end end @@ -188,7 +194,7 @@ function render(doc::Documents.Document, settings::HTML=HTML()) ctx.search_js = copy_asset("search.js", doc) push!(ctx.local_assets, copy_asset("documenter.css", doc)) - append!(ctx.local_assets, doc.user.assets) + append!(ctx.local_assets, settings.assets) for navnode in doc.internal.navlist render_page(ctx, navnode) @@ -273,7 +279,7 @@ function render_head(ctx, navnode) meta[:name => "viewport", :content => "width=device-width, initial-scale=1.0"], title(page_title), - analytics_script(ctx.doc.user.analytics), + analytics_script(ctx.settings.analytics), canonical_link_element(ctx.settings.canonical, src), diff --git a/test/examples/make.jl b/test/examples/make.jl index 5607179b84..a96bfe5822 100644 --- a/test/examples/make.jl +++ b/test/examples/make.jl @@ -146,22 +146,46 @@ examples_html_local_doc = makedocs( ), ) -# Build with pretty URLs and canonical links +# Build with pretty URLs and canonical links and a PNG logo @info("Building mock package docs: HTMLWriter / deployment build") -examples_html_deploy_doc = makedocs( - debug = true, - root = examples_root, - build = "builds/html-deploy", - doctestfilters = [r"Ptr{0x[0-9]+}"], - assets = [ - "assets/favicon.ico", - "assets/custom.css" - ], - sitename = "Documenter example", - pages = htmlbuild_pages, - doctest = false, - Documenter.HTML( - prettyurls = true, - canonical = "https://example.com/stable", + +function withassets(f, assets...) + src(asset) = joinpath(@__DIR__, asset) + dst(asset) = joinpath(@__DIR__, "src/assets/$(basename(asset))") + for asset in assets + isfile(src(asset)) || error("$(asset) is missing") + end + for asset in assets + cp(src(asset), dst(asset)) + end + rv = try + f() + catch exception + @warn "f() threw an exception" exception + nothing + end + for asset in assets + rm(dst(asset)) + end + return rv +end + +examples_html_deploy_doc = withassets("images/logo.png", "images/logo.jpg", "images/logo.gif") do + makedocs( + debug = true, + root = examples_root, + build = "builds/html-deploy", + doctestfilters = [r"Ptr{0x[0-9]+}"], + assets = [ + "assets/favicon.ico", + "assets/custom.css" + ], + sitename = "Documenter example", + pages = htmlbuild_pages, + doctest = false, + Documenter.HTML( + prettyurls = true, + canonical = "https://example.com/stable", + ) ) -) +end