Merge pull request #953 from JuliaDocs/mp/logo-formats

Update HTMLWriter logo handling and arguments

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

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",

src/Documenter.jl

@@ -194,21 +194,24 @@ 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
         ```
         $kw = ...
         ```
         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)

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(