Merge pull request #1061 from JuliaDocs/mp/writer-not-plugin

Do not declare writers <: Plugin

CHANGELOG.md

@@ -28,6 +28,8 @@
 
 * ![Bugfix][badge-bugfix] The HTML output now outputs HTML files for pages that are not referenced in the `pages` keyword too (Documenter finds them according to their extension). But they do exists outside of the standard navigation hierarchy (as defined by `pages`). This fixes a bug where these pages could still be referenced by `@ref` links and `@contents` blocks, but in the HTML output, the links ended up being broken. ([#1031][github-1031], [#1047][github-1047])
 
+* ![Bugfix][badge-bugfix] `makedocs` now throws an error when the format objects (`Documenter.HTML`, `LaTeX`, `Markdown`) get passed positionally. The format types are no longer subtypes of `Documenter.Plugin`. ([#1046][github-1046], [#1061][github-1061])
+
 * ![Experimental][badge-experimental] ![Feature][badge-feature] The current working directory when evaluating `@repl` and `@example` blocks can now be set to a fixed directory by passing the `workdir` keyword to `makedocs`. _The new keyword and its behaviour are experimental and not part of the public API._ ([#1013][github-1013], [#1025][github-1025])
 
 ## Version `v0.22.5`
@@ -363,8 +365,10 @@
 [github-1031]: https://github.com/JuliaDocs/Documenter.jl/issues/1031
 [github-1034]: https://github.com/JuliaDocs/Documenter.jl/pull/1034
 [github-1037]: https://github.com/JuliaDocs/Documenter.jl/pull/1037
+[github-1046]: https://github.com/JuliaDocs/Documenter.jl/issues/1046
 [github-1047]: https://github.com/JuliaDocs/Documenter.jl/pull/1047
 [github-1054]: https://github.com/JuliaDocs/Documenter.jl/pull/1054
+[github-1061]: https://github.com/JuliaDocs/Documenter.jl/pull/1061
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/Documenter.jl

@@ -31,6 +31,7 @@ a new `T` object will be created.
 """
 abstract type Plugin end
 
+abstract type Writer end
 
 # Submodules
 # ----------

src/Documents.jl

@@ -13,7 +13,8 @@ import ..Documenter:
     Documenter,
     Anchors,
     Utilities,
-    Plugin
+    Plugin,
+    Writer
 
 import ..Documenter.Utilities.Markdown2
 using DocStringExtensions
@@ -211,7 +212,7 @@ struct User
     source  :: String  # Parent directory is `.root`. Where files are read from.
     build   :: String  # Parent directory is also `.root`. Where files are written to.
     workdir :: Union{Symbol,String} # Parent directory is also `.root`. Where code is executed from.
-    format  :: Vector{Plugin} # What format to render the final document with?
+    format  :: Vector{Writer} # 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..
@@ -285,7 +286,7 @@ function Document(plugins = nothing;
     Utilities.check_kwargs(others)
 
     if !isa(format, AbstractVector)
-        format = Plugin[format]
+        format = Writer[format]
     end
 
     if version == "git-commit"
@@ -332,9 +333,9 @@ function Document(plugins = nothing;
     if plugins !== nothing
         for plugin in plugins
             plugin isa Plugin ||
-                throw("$(typeof(plugin)) is not a subtype of `Documenter.Plugin`.")
+                throw(ArgumentError("$(typeof(plugin)) is not a subtype of `Documenter.Plugin`."))
             haskey(plugin_dict, typeof(plugin)) &&
-                throw("only one copy of $(typeof(plugin)) may be passed.")
+                throw(ArgumentError("only one copy of $(typeof(plugin)) may be passed."))
             plugin_dict[typeof(plugin)] = plugin
         end
     end

src/Writers/HTMLWriter.jl

@@ -125,7 +125,7 @@ The type of the asset (i.e. whether it is going to be included with a `<script>`
 `<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
+struct HTML <: Documenter.Writer
     prettyurls  :: Bool
     disable_git :: Bool
     edit_branch :: Union{String, Nothing}

src/Writers/LaTeXWriter.jl

@@ -38,7 +38,7 @@ The `makedocs` argument `authors` should also be specified, it will be used for
 **`platform`** sets the platform where the tex-file is compiled, either `"native"` (default) or `"docker"`.
 See [Other Output Formats](@ref) for more information.
 """
-struct LaTeX <: Documenter.Plugin
+struct LaTeX <: Documenter.Writer
     platform::String
     function LaTeX(; platform = "native")
         platform ∈ ("native", "docker") || throw(ArgumentError("unknown platform: $platform"))

src/Writers/MarkdownWriter.jl

@@ -17,7 +17,7 @@ module _Markdown
 end
 const MarkdownStdlib = _Markdown.Markdown
 
-struct Markdown <: Documenter.Plugin
+struct Markdown <: Documenter.Writer
 end
 
 # return the same file with the extension changed to .md

test/runtests.jl

@@ -55,6 +55,9 @@ println("="^50)
 
     # A simple build evaluating code outside build directory
     include("workdir/tests.jl")
+
+    # Passing a writer positionally (https://github.com/JuliaDocs/Documenter.jl/issues/1046)
+    @test_throws ArgumentError makedocs(sitename="", HTML())
 end
 
 # Additional tests