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 @@ + + + + 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 `