Warn on unsupported arguments in contents, index, autodocs, and meta blocks

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `id` anchors may now start with a numeric digit. ([#744], [#2325])
 * Documenter prints a more informative warning now if there is unexpected Julia interpolation in the Markdown (e.g. from errant `$` signs). ([#2288], [#2327])
+* Documenter now warns when it encounters invalid keys in the various key-value at-blocks. ([#2306], [#2324])
 
 ### Fixed
 

src/documents.jl

@@ -96,6 +96,13 @@
             source  = error("missing value for `source` in `IndexNode`."),
             others...
         )
+        if !isempty(others)
+            @warn(
+                "In file $source: the following unsupported keyword " *
+                "arguments have been set in the `@index` node:\n" *
+                join([string(k, " = ", v) for (k, v) in others], "\n"),
+            )
+        end
         new(Pages, Modules, Order, build, source, [], codeblock)
     end
 end
@@ -121,6 +128,13 @@
         if Depth isa Integer
             Depth = 1:Depth
         end
+        if !isempty(others)
+            @warn(
+                "In file $source: the following unsupported keyword " *
+                "arguments have been set in the `@contents` node:\n" *
+                join([string(k, " = ", v) for (k, v) in others], "\n"),
+            )
+        end
         new(Pages, first(Depth), last(Depth), build, source, [], codeblock)
     end
 end

src/expander_pipeline.jl

@@ -289,7 +289,17 @@
     lines = Documenter.find_block_in_file(x.code, page.source)
     @debug "Evaluating @meta block:\n$(x.code)"
     for (ex, str) in Documenter.parseblock(x.code, doc, page)
+        # If not `isassign`, this might be a comment, or any code that the user
+        # wants to hide. We should probably warn, but it is common enough that
+        # we will silently skip for now.
         if Documenter.isassign(ex)
+            if !(ex.args[1] in (:Currentmodule, :DocTestSetup, :DocTestFilters, :EditURL, :Description, :Draft))
+                source = Documenter.locrepr(page.source, lines)
+                @warn(
+                    "In $source: `@meta` block has an unsupported " *
+                    "keyword argument: $(ex.args[1])",
+                )
+            end
             try
                 meta[ex.args[1]] = Core.eval(Main, ex.args[2])
             catch err
@@ -460,8 +470,14 @@
             try
                 if ex.args[1] == :Filter
                     fields[ex.args[1]] = Core.eval(Main, ex.args[2])
-                else
+                elseif ex.args[1] in (:Modules, :Order, :Pages, :Public, :Private)
                     fields[ex.args[1]] = Core.eval(curmod, ex.args[2])
+                else
+                    source = Documenter.locrepr(page.source, lines)
+                    @warn(
+                        "In $source: `@autodocs` block has an unsupported " *
+                        "keyword argument: $(ex.args[1])",
+                    )
                 end
             catch err
                 @docerror(doc, :autodocs_block,

test/errors/src/index.md

@@ -9,10 +9,12 @@ parse error
 
 ```@meta
 CurrentModule = NonExistentModule
+draft = true  # invalid keyword
 ```
 
 ```@autodocs
 Modules = [NonExistentModule]
+pages = []  # invalid keyword
 ```
 
 ```@eval
@@ -23,6 +25,14 @@ NonExistentModule
 # comment in a @docs block
 ```
 
+```@index
+foo = 1
+```
+
+```@contents
+foo = 1
+```
+
 [`foo(x::Foo)`](@ref) creates an [`UndefVarError`](@ref) when `eval`d
 for the type signature, since `Foo` is not defined.