Add checkdocs_ignore to exclude certain modules from checkdocs

CHANGELOG.md

@@ -3,8 +3,14 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
 ## Version [v1.6.0] - 2024-08-20
 
+### Added
+
+ * A `checkdocs_ignored_modules` keyword argument to `makedocs(...)`, which prevents `checkdocs` from warning about missing documentation in certain modules.
+
 ### Changed
 
 * The MathJax3 setup now uses `tex-svg-full.js` and additionally draws in `mhchem` by default, allowing for chemistry symbols to be rendered (consistent with Pluto.jl). ([#2549])

src/documents.jl

@@ -313,6 +313,7 @@ struct User
  linkcheck_ignore::Vector{Union{String,Regex}} # ..and then ignore (some of) them.
  linkcheck_timeout::Real # ..but only wait this many seconds for each one.
  checkdocs::Symbol # Check objects missing from `@docs` blocks. `:none`, `:exports`, or `:all`.
+ checkdocs_ignored_modules::Vector{Module} # ..and then ignore (some of) them.
  doctestfilters::Vector{Regex} # Filtering for doctests
  warnonly::Vector{Symbol} # List of docerror groups that should only warn, rather than cause a build failure
  pages :: Vector{Any} # Ordering of document pages specified by the user.
@@ -386,6 +387,7 @@ function Document(;
  linkcheck_ignore :: Vector = [],
  linkcheck_timeout :: Real = 10,
  checkdocs::Symbol = :all,
+ checkdocs_ignored_modules::Vector{Module} = Module[],
  doctestfilters::Vector{Regex}= Regex[],
  warnonly :: Union{Bool,Symbol,Vector{Symbol}} = Symbol[],
  modules :: Union{Module, Vector{Module}} = Module[],
@@ -451,6 +453,7 @@ function Document(;
  linkcheck_ignore,
  linkcheck_timeout,
  checkdocs,
+ checkdocs_ignored_modules,
  doctestfilters,
  warnonly,
  pages,
@@ -491,7 +494,7 @@ function Document(;
 
  blueprint = DocumentBlueprint(
  Dict{String, Page}(),
- submodules(modules),
+ submodules(modules; ignore=Set(checkdocs_ignored_modules)),
  )
  Document(user, internal, plugin_dict, blueprint)
 end

src/makedocs.jl

@@ -178,7 +178,15 @@ are `:all` (check all names; the default), `:exports` (check only exported names
 `:none` (no checks are performed).
 
 By default, if the document check detect any errors, it will fail the documentation build.
-This behavior can be relaxed with the `warnonly` keyword.
+This behavior can be relaxed with the `warnonly` or `checkdocs_ignored_modules` keywords.
+
+**`checkdocs_ignored_modules`** prevents `checkdocs` from checking modules supplied as a list
+of module objects. It will also cause all submodules of these module to be ignored. It can be
+useful for completely private modules including modules which have been vendored from
+elsewhere.
+
+Note that `checkdocs_ignored_modules` does not conversely verify that these docstrings are *not*
+included in the documentation.
 
 **`linkcheck`** -- if set to `true` [`makedocs`](@ref) uses `curl` to check the status codes
 of external-pointing links, to make sure that they are up-to-date. The links and their

src/utilities/utilities.jl

@@ -201,19 +201,19 @@ end
 """
 Returns the set of submodules of a given root module/s.
 """
-function submodules(modules::Vector{Module})
+function submodules(modules::Vector{Module}; ignore = Set{Module}())
  out = Set{Module}()
  for each in modules
- submodules(each, out)
+ submodules(each, out; ignore=ignore)
  end
  out
 end
-function submodules(root::Module, seen = Set{Module}())
+function submodules(root::Module, seen = Set{Module}(); ignore = Set{Module}())
  push!(seen, root)
  for name in names(root, all=true)
  if Base.isidentifier(name) && isdefined(root, name) && !isdeprecated(root, name)
  object = getfield(root, name)
- if isa(object, Module) && !(object in seen) && parentmodule(object::Module) == root
+ if isa(object, Module) && !(object in seen) && !(object in ignore) && parentmodule(object::Module) == root
  submodules(object, seen)
  end
  end

test/missingdocs/make.jl

@@ -13,6 +13,15 @@ module MissingDocs
  g(x) = x
 end
 
+module MissingDocsSubmodule
+ module UndocumentedSubmodule
+ export f
+
+ "exported"
+ f(x) = x
+ end
+end
+
 @testset "missing docs" begin
  for (sym, n_expected) in zip([:none, :exports, :all], [0, 1, 2])
  kwargs = (
@@ -38,6 +47,23 @@ end
  checkdocs = :all,
  sitename = "MissingDocs Checks",
  )
+
+ for (ignore, n_expected) in zip([false, true] , [1, 0])
+ kwargs = (
+ root = dirname(@__FILE__),
+ source = joinpath("src", "none"),
+ build = joinpath("build", "submodule"),
+ modules = MissingDocsSubmodule,
+ checkdocs = :all,
+ sitename = "MissingDocsSubmodule Checks",
+ warnonly = true,
+ checkdocs_ignored_modules = ignore ? Module[MissingDocsSubmodule.UndocumentedSubmodule] : Module[],
+ )
+ @quietly @test makedocs(; kwargs...) === nothing
+
+ doc = Documenter.Document(; kwargs...)
+ @quietly @test Documenter.missingdocs(doc) == n_expected
+ end
 end
 
 end