change format::Symbol to format::Plugin

docs/make.jl

@@ -1,7 +1,14 @@
-using Documenter, DocumenterTools
+using Documenter, DocumenterTools, DocumenterLaTeX, DocumenterMarkdown
 
 makedocs(
     modules = [Documenter, DocumenterTools],
+    # format = Documenter.HTML(
+    #     # Use clean URLs, unless built as a "local" build
+    #     prettyurls = !("local" in ARGS),
+    #     canonical = "https://juliadocs.github.io/Documenter.jl/stable/",
+    # ),
+    format = Documenter.Writers.LaTeXWriter.LaTeX(engine = "docker"),
+    # format = Documenter.Writers.MarkdownWriter.Markdown(),
     clean = false,
     assets = ["assets/favicon.ico"],
     sitename = "Documenter.jl",
@@ -35,7 +42,6 @@ makedocs(
                 "lib/internals/documents.md",
                 "lib/internals/dom.md",
                 "lib/internals/expanders.md",
-                "lib/internals/formats.md",
                 "lib/internals/mdflatten.md",
                 "lib/internals/selectors.md",
                 "lib/internals/textdiff.md",
@@ -45,11 +51,6 @@ makedocs(
         ],
         "contributing.md",
     ],
-    Documenter.HTML(
-        # Use clean URLs, unless built as a "local" build
-        prettyurls = !("local" in ARGS),
-        canonical = "https://juliadocs.github.io/Documenter.jl/stable/",
-    ),
 )
 
 deploydocs(

src/Documenter.jl

@@ -176,26 +176,78 @@ ignored.
 any errors with the document in the previous build phases.
 
 ## Output formats
-**`format`** allows the output format to be specified. The default value is `:html`. Other
-formats can be enabled by using other packages. For examples, see the `DocumenterMarkdown`
-and `DocumenterLaTeX` packages.
+**`format`** allows the output format to be specified. The default format is
+[`Documenter.HTML`](@ref) which creates a set of HTML files.
 
-Documenter is designed to support multiple output formats. By default it is creates a set of
-HTML files, but the output format can be controlled with the `format` keyword. The different
-output formats may require additional keywords to be specified via plugins. The keywords for
-the default HTML output are documented for the [`Writers.HTMLWriter.HTML`](@ref) type.
-
-The default `:html` output format creates a set of HTML files, but Documenter is designed to
-support multiple output formats. Via plugin packages, Documenter also supports e.g. Markdown
-/ MkDocs and LaTeX / PDF outputs. See the [Other Output Formats](@ref) for more information.
+There are other possible formats that are enabled by using other addon-packages.
+For examples, the `DocumenterMarkdown` package define the `DocumenterMarkdown.Markdown()`
+format for use with e.g. MkDocs, and the `DocumenterLaTeX` package define the
+`DocumenterLaTeX.LaTeX()` format for LaTeX / PDF output.
+See the [Other Output Formats](@ref) for more information.
 
 # See Also
 
 A guide detailing how to document a package using Documenter's [`makedocs`](@ref) is provided
 in the [setup guide in the manual](@ref Package-Guide).
 """
-function makedocs(components...; debug = false, kwargs...)
-    document = Documents.Document(components; kwargs...)
+function makedocs(components...; debug = false, format = HTML(),
+                  html_prettyurls::Union{Bool, Nothing} = nothing, # deprecated
+                  html_disable_git::Union{Bool, Nothing} = nothing, # deprecated
+                  html_edit_branch::Union{String, Nothing} = nothing, # deprecated
+                  html_canonical::Union{String, Nothing} = nothing, # deprecated
+                  kwargs...)
+    # html_ keywords deprecation
+    html_keywords = Dict()
+    @noinline function html_warn(kw)
+        Base.depwarn("""
+        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 = ...)
+        ```
+        """, :makedocs)
+    end
+    if html_prettyurls !== nothing
+        html_warn("html_prettyurls")
+        html_keywords[:prettyurls] = html_prettyurls
+    end
+    if html_disable_git !== nothing
+        html_warn("html_disable_git")
+        html_keywords[:disable_git] = html_disable_git
+    end
+    if html_edit_branch !== nothing
+        html_warn("html_edit_branch")
+        html_keywords[:edit_branch] = html_edit_branch
+    end
+    if html_canonical !== nothing
+        html_warn("html_canonical")
+        html_keywords[:canonical] = html_canonical
+    end
+    # deprecation of format as Symbols
+    function fmt(f)
+        if format === :html
+            Base.depwarn("`format = :html` is deprecated, use `format = Documenter.HTML()` instead.", :makedocs)
+            return Writers.HTMLWriter.HTML(html_keywords...)
+        elseif format === :latex
+            Base.depwarn("`format = :latex` is deprecated, use `format = DocumenterLaTeX.LaTeX()` instead.", :makedocs)
+            return Writer.LaTeXWriter.LaTeX()
+        elseif format === :markdown
+            Base.depwarn("`format = :markdown` is deprecated, use `format = DocumenterMarkdown.Markdown()` instead.", :makedocs)
+            return Writer.MarkdownWriter.Markdown()
+        end
+    end
+    if isa(format, AbstractVector{<:Symbol})
+        format = fmt.(format)
+    elseif isa(format, Symbol)
+        format = fmt(format)
+    end
+
+
+    document = Documents.Document(components; format=format, kwargs...)
     cd(document.user.root) do
         Selectors.dispatch(Builder.DocumentPipeline, document)
     end

src/Documents.jl

@@ -184,7 +184,7 @@ struct User
     root    :: String  # An absolute path to the root directory of the document.
     source  :: String  # Parent directory is `.root`. Where files are read from.
     build   :: String  # Parent directory is also `.root`. Where files are written to.
-    format  :: Vector{Symbol} # What format to render the final document with?
+    format  :: Vector{Any} # What format to render the final document with?
     clean   :: Bool           # Empty the `build` directory before starting a new build?
     doctest :: Union{Bool,Symbol} # Run doctests?
     linkcheck::Bool           # Check external links..
@@ -233,12 +233,11 @@ struct Document
     plugins  :: Dict{DataType, Plugin}
 end
 
-Document(; kwargs...) = Document(nothing; kwargs...)
-function Document(plugins;
+function Document(plugins = nothing;
         root     :: AbstractString   = Utilities.currentdir(),
         source   :: AbstractString   = "src",
         build    :: AbstractString   = "build",
-        format   :: Any              = :html,
+        format   :: Any              = Documenter.HTML(),
         clean    :: Bool             = true,
         doctest  :: Union{Bool,Symbol} = true,
         linkcheck:: Bool             = false,
@@ -254,16 +253,13 @@ function Document(plugins;
         authors  :: AbstractString   = "",
         analytics :: AbstractString  = "",
         version :: AbstractString    = "",
-        html_prettyurls  :: Union{Bool, Nothing}   = nothing, # deprecated
-        html_disable_git :: Union{Bool, Nothing}   = nothing, # deprecated
-        html_edit_branch :: Union{String, Nothing} = nothing, # deprecated
-        html_canonical   :: Union{String, Nothing} = nothing, # deprecated
         others...
     )
     Utilities.check_kwargs(others)
 
-    fmt = Formats.fmt(format)
-    @assert !isempty(fmt) "No formats provided."
+    if !isa(format, AbstractVector)
+        format = [format]
+    end
 
     if version == "git-commit"
         version = "git:$(Utilities.get_commit_short(root))"
@@ -273,7 +269,7 @@ function Document(plugins;
         root,
         source,
         build,
-        fmt,
+        format,
         clean,
         doctest,
         linkcheck,
@@ -317,69 +313,6 @@ function Document(plugins;
         end
     end
 
-    # html keywords depreciation
-    html_keywords = Dict()
-    if html_prettyurls !== nothing
-        Base.depwarn("""The `html_prettyurls` keyword argument has been moved to the
-            `HTML` plugin. To fix this warning, replace
-            ```
-                html_prettyurls = ...,
-            ```
-            with
-            ```
-                HTML(prettyurls = ...),
-            ```
-            """, :deploydocs)
-        html_keywords[:prettyurls] = html_prettyurls
-    end
-    if html_disable_git !== nothing
-        Base.depwarn("""The `html_disable_git` keyword argument has been moved to the
-            `HTML` plugin. To fix this warning, replace
-            ```
-                html_disable_git = ...,
-            ```
-            with
-            ```
-                HTML(disable_git = ...),
-            ```
-            """, :deploydocs)
-        html_keywords[:disable_git] = html_disable_git
-    end
-    if html_edit_branch !== nothing
-        Base.depwarn("""The `html_edit_branch` keyword argument has been moved to the
-            `HTML` plugin. To fix this warning, replace
-            ```
-                html_edit_branch = ...,
-            ```
-            with
-            ```
-                HTML(edit_branch = ...),
-            ```
-            """, :deploydocs)
-        html_keywords[:edit_branch] = html_edit_branch
-    end
-    if html_canonical !== nothing
-        Base.depwarn("""The `html_canonical` keyword argument has been moved to the
-            `HTML` plugin. To fix this warning, replace
-            ```
-                html_canonical = ...,
-            ```
-            with
-            ```
-                HTML(canonical = ...),
-            ```
-            """, :deploydocs)
-        html_keywords[:canonical] = html_canonical
-    end
-    if !isempty(html_keywords)
-        if Documenter.Writers.HTMLWriter.HTML in keys(plugin_dict)
-            throw("Documenter received both an `HTML` plugin and `html_*` keywords.")
-        end
-
-        plugin_dict[Documenter.Writers.HTMLWriter.HTML] =
-            Documenter.Writers.HTMLWriter.HTML(; html_keywords...)
-    end
-
     Document(user, internal, plugin_dict)
 end
 

src/Formats.jl

@@ -9,16 +9,6 @@ import ..Documenter
 
 using DocStringExtensions
 
-"""
-Represents the output format. Possible values are `Markdown`, `LaTeX`, and `HTML`.
-"""
-@enum(
-    Format,
-    Markdown,
-    LaTeX,
-    HTML,
-)
-
 """
 $(SIGNATURES)
 
@@ -43,20 +33,4 @@ function extension(f::Symbol)
         error("unexpected format.")
 end
 
-# `fmt` -- convert a format spec to a vector of symbols.
-const DEPRECATION_MAPPING = Dict(
-    Markdown => :markdown,
-    LaTeX    => :latex,
-    HTML     => :html,
-)
-function _fmt(f::Format)
-    s = DEPRECATION_MAPPING[f]
-    Base.depwarn("`$(f)` is deprecated use `:$(s)` for `format = ...`.", :fmt)
-    return s
-end
-fmt(f::Format) = [_fmt(f)]
-fmt(v::Vector{Format}) = map(_fmt, v)
-fmt(s::Symbol) = [s]
-fmt(v::Vector{Symbol}) = v
-
 end

src/Writers/HTMLWriter.jl

@@ -162,7 +162,7 @@ mutable struct HTMLContext
     search_navnode :: Documents.NavNode
     local_assets :: Vector{String}
 end
-HTMLContext(doc) = HTMLContext(doc, Documents.getplugin(doc, HTML), "", [], "", "", IOBuffer(), "", Documents.NavNode("search", "Search", nothing), [])
+HTMLContext(doc, settings) = HTMLContext(doc, settings, "", [], "", "", IOBuffer(), "", Documents.NavNode("search", "Search", nothing), [])
 
 """
 Returns a page (as a [`Documents.Page`](@ref) object) using the [`HTMLContext`](@ref).
@@ -171,10 +171,10 @@ getpage(ctx, path) = ctx.doc.internal.pages[path]
 getpage(ctx, navnode::Documents.NavNode) = getpage(ctx, navnode.page)
 
 
-function render(doc::Documents.Document)
+function render(doc::Documents.Document, settings::HTML)
     !isempty(doc.user.sitename) || error("HTML output requires `sitename`.")
 
-    ctx = HTMLContext(doc)
+    ctx = HTMLContext(doc, settings)
     ctx.search_index_js = "search_index.js"
 
     copy_asset("arrow.svg", doc)

src/Writers/LaTeXWriter.jl

@@ -13,6 +13,27 @@ navigation menu. It goes into the `\\title` LaTeX command.
 
 """
 module LaTeXWriter
+import ...Documenter: Documenter
+
+"""
+    LaTeXWriter.LaTeX(kwargs...)
+
+Sets the behavior of [`LaTeXWriter`](@ref).
+
+# Keyword arguments
+
+**`engine`** sets the latex engine; (natively installed) `"latexmk"`
+(default) or `"docker"` using the
+[`juliadocs/documenter-latex`](https://hub.docker.com/r/juliadocs/documenter-latex/)
+docker image with required tex installation and fonts included.
+"""
+struct LaTeX <: Documenter.Plugin
+    engine::String
+    function LaTeX(; engine = "latexmk")
+        engine ∈ ("latexmk", "docker") || throw(ArgumentError("unknown engine: $engine"))
+        return new(engine)
+    end
+end
 
 import ...Documenter:
     Anchors,
@@ -53,7 +74,7 @@ const DOCUMENT_STRUCTURE = (
     "subparagraph",
 )
 
-function render(doc::Documents.Document)
+function render(doc::Documents.Document, settings::LaTeX)
     mktempdir() do path
         cp(joinpath(doc.user.root, doc.user.build), joinpath(path, "build"))
         cd(joinpath(path, "build")) do
@@ -86,17 +107,16 @@ function render(doc::Documents.Document)
             cp(STYLE, "documenter.sty")
 
             # compile .tex and copy over the .pdf file if compile_tex return true
-            status = compile_tex(texfile)
+            status = compile_tex(doc, settings, texfile)
             status && cp(pdffile, joinpath(doc.user.root, doc.user.build, pdffile); force = true)
         end
     end
 end
 
 const DOCKER_IMAGE_TAG = "0.1"
 
-function compile_tex(texfile)
-    engine = get(ENV, "DOCUMENTER_LATEX_ENGINE", "latexmk") # TODO: make this configurable from makedocs
-    if engine == "latexmk"
+function compile_tex(doc, settings, texfile)
+    if settings.engine == "latexmk"
         Sys.which("latexmk") === nothing && (@error "LaTeXWriter: latexmk command not found."; return false)
         @info "LaTeXWriter: using latexmk to compile tex."
         try
@@ -108,7 +128,7 @@ function compile_tex(texfile)
                    "Logs and partial output can be found in $(Utilities.locrepr(logs))." exception = err
             return false
         end
-    elseif engine == "docker"
+    elseif settings.engine == "docker"
         Sys.which("docker") === nothing && (@error "LaTeXWriter: docker command not found."; return false)
         @info "LaTeXWriter: using docker to compile tex."
         script = """