diff --git a/CHANGELOG.md b/CHANGELOG.md index 2af111b037..24c714dbd5 100644 --- a/CHANGELOG.md +++ b/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]) diff --git a/src/documents.jl b/src/documents.jl index e840d418b8..916d82da12 100644 --- a/src/documents.jl +++ b/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 diff --git a/src/makedocs.jl b/src/makedocs.jl index 68aca25a0c..a0407a8b6e 100644 --- a/src/makedocs.jl +++ b/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 diff --git a/src/utilities/utilities.jl b/src/utilities/utilities.jl index 1abbdb337e..66c2307fc0 100644 --- a/src/utilities/utilities.jl +++ b/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 diff --git a/test/missingdocs/make.jl b/test/missingdocs/make.jl index 4399ea2aa9..40be86e1bf 100644 --- a/test/missingdocs/make.jl +++ b/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