Fix and update docs to Documenter 1

[IanButterworth]

Fixes #3658

[IanButterworth]

It seems that Documenter is being strict about every module under Pkg.. which seems excessive.

We seem to set modules as recommended

Pkg.jl/docs/make.jl

Line 28 in cbc7fa8

modules = [Pkg],

https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs

[ Info: CheckDocument: running document checks.
┌ Error: 38 docstrings not included in the manual:
│ 
│     Pkg.PlatformEngines.download_verify :: Tuple{AbstractString, Union{Nothing, AbstractString}, AbstractString}
│     Pkg.GitTools.tree_hash :: Union{Tuple{HashType}, Tuple{Type{HashType}, AbstractString}} where HashType
│     Pkg.generate
│     Pkg.Resolve.simplify_graph! :: Union{Tuple{Pkg.Resolve.Graph}, Tuple{Pkg.Resolve.Graph, Set{Int64}}}
│     Pkg.Resolve.greedysolver :: Tuple{Pkg.Resolve.Graph}
│     Pkg.Resolve.compute_eq_classes! :: Tuple{Pkg.Resolve.Graph}
│     Pkg.GitTools.contains_files :: Tuple{AbstractString}
│     Pkg.Resolve.verify_solution :: Tuple{Vector{Int64}, Pkg.Resolve.Graph}
│     Pkg.Resolve.resolve :: Tuple{Pkg.Resolve.Graph}
│     Pkg.Resolve.range_compressed_versionspec :: Union{Tuple{Any}, Tuple{Any, Any}}
│     Pkg.is_manifest_current
│     Pkg.REPLMode.enforce_option :: Tuple{Vector{Pkg.REPLMode.Option}, Dict{String, Pkg.REPLMode.OptionSpec}}
│     Pkg.Resolve.get_resolve_log :: Tuple{Pkg.Resolve.Graph}
│     Pkg.Resolve.showlog :: Tuple{IO, Pkg.Resolve.ResolveLog}
│     Pkg.Resolve.showlog :: Tuple{IO, Pkg.Resolve.ResolveLog, Base.UUID}
│     Pkg.Resolve.propagate_constraints! :: Union{Tuple{Pkg.Resolve.Graph}, Tuple{Pkg.Resolve.Graph, Set{Int64}}}
│     Pkg.REPLMode.Command :: Tuple{Pkg.REPLMode.Statement}
│     Pkg.Resolve.prune_graph! :: Tuple{Pkg.Resolve.Graph}
│     Pkg.Artifacts.extract_all_hashes :: Tuple{String}
│     Pkg.Resolve.add_fixed! :: Tuple{Pkg.Resolve.Graph, Dict{Base.UUID, Pkg.Resolve.Fixed}}
│     Pkg.PlatformEngines.download_verify_unpack :: Tuple{AbstractString, Union{Nothing, AbstractString}, AbstractString}
│     Pkg.Resolve.disable_unreachable! :: Union{Tuple{Pkg.Resolve.Graph}, Tuple{Pkg.Resolve.Graph, Set{Int64}}}
│     Pkg.Resolve.enforce_optimality! :: Tuple{Vector{Int64}, Pkg.Resolve.Graph}
│     Pkg.PlatformEngines.package :: Tuple{AbstractString, AbstractString}
│     Pkg.Resolve.add_reqs! :: Tuple{Pkg.Resolve.Graph, Dict{Base.UUID, Pkg.Versions.VersionSpec}}
│     Pkg.upgrade_manifest
│     Pkg.BinaryPlatforms.platform_key_abi :: Tuple{}
│     Pkg.API.gc :: Union{Tuple{}, Tuple{Pkg.Types.Context}}
│     Pkg.PlatformEngines.verify :: Tuple{AbstractString, AbstractString}
│     Pkg.GitTools.blob_hash :: Union{Tuple{HashType}, Tuple{Type{HashType}, AbstractString}} where HashType
│     Pkg.PlatformEngines.register_auth_error_handler :: Tuple{Union{Regex, AbstractString}, Any}
│     Pkg.Resolve.compute_output_dict :: Tuple{Vector{Int64}, Pkg.Resolve.Graph}
│     Pkg.Resolve._uninstall_unreachable! :: Tuple{Vector{Int64}, Vector{Union{Int64, Symbol}}, Pkg.Resolve.Graph}
│     Pkg.REPLMode.parse_package :: Tuple{Vector{Pkg.REPLMode.QString}, Any}
│     Pkg.PlatformEngines.deregister_auth_error_handler :: Tuple{Union{Regex, String}, Any}
│     Pkg.BinaryPlatforms.valid_dl_path :: Tuple{AbstractString, Base.BinaryPlatforms.AbstractPlatform}
│     Pkg.Resolve.check_constraints :: Tuple{Pkg.Resolve.Graph}
│     Pkg.Resolve.sanity_check :: Union{Tuple{Pkg.Resolve.Graph}, Tuple{Pkg.Resolve.Graph, Set{Base.UUID}}, Tuple{Pkg.Resolve.Graph, Set{Base.UUID}, Bool}}
│ 
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in canonical @docs or @autodocs blocks.
└ @ Documenter ~/.julia/packages/Documenter/cxHBW/src/utilities/utilities.jl:44
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered an error [:missing_docs] -- terminating build before rendering.

[mortenpi]

FWIW, setting warnonly = :missing_docs would allow this to pass at least. This is the issue of non-public functions having docstrings that people don't want to include in the manual, for which we would really need a better approach for. The current standard approach (from my perspective) is to have a manually-curated internals page that includes all these docstrings.

[KristofferC]

The current standard approach (from my perspective) is to have a manually-curated internals page that includes all these docstrings.

But these docstrings are more or less glorified comments and there is no need/desire to have them anywhere in the manual, polluting the searches (ref JuliaDocs/Documenter.jl#2241) etc.

[mortenpi]

But these docstrings are more or less glorified comments and there is no need/desire to have them anywhere in the manual

Don't disagree, hence

for which we would really need a better approach for

[KristofferC]

So

warnonly = :missing_docs

for now I guess.

[IanButterworth]

│ - ✘ ENV["DOCUMENTER_KEY"] or ENV["GITHUB_TOKEN"] exists and is non-empty

Odd. DOCUMENTER_KEY is declared in the yml and it's not like docs weren't deploying before

[KristofferC]

But isn't that a "secret" and this PR is from a fork (which I don't think has access to those secrets). I think this could have been merged.

[IanButterworth]

oh right. Ok. Yeah, I updated this because there were a bunch of CI changes on master. Just checking