Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: check that exports are documented, with check for regression/improvement #55267

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
+28 −2
Open

Docs: check that exports are documented, with check for regression/improvement #55267

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
955006b
check that all exports are documented
IanButterworth Jul 26, 2024
a5ad2da
warn only. Add comments
IanButterworth Jul 26, 2024
7a59bd7
add check for regressions or improvements
IanButterworth Jul 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 28 additions & 2 deletions doc/make.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Pkg.instantiate()

using Documenter
import LibGit2
using Logging: with_logger, NullLogger

baremodule GenStdLib end

Expand Down Expand Up @@ -371,21 +372,46 @@ else
end

const output_path = joinpath(buildroot, "doc", "_build", (render_pdf ? "pdf" : "html"), "en")
makedocs(
doc = makedocs(
build = output_path,
modules = [Main, Base, Core, [Base.root_module(Base, stdlib.stdlib) for stdlib in STDLIB_DOCS]...],
clean = true,
doctest = ("doctest=fix" in ARGS) ? (:fix) : ("doctest=only" in ARGS) ? (:only) : ("doctest=true" in ARGS) ? true : false,
linkcheck = "linkcheck=true" in ARGS,
linkcheck_ignore = ["https://bugs.kde.org/show_bug.cgi?id=136779"], # fails to load from nanosoldier?
checkdocs = :none,
checkdocs = :exports, # we really want :public but thats not available yet https://github.com/JuliaDocs/Documenter.jl/issues/1506
warnonly = :missing_docs, # warn about missing docstrings, but don't fail
format = format,
sitename = "The Julia Language",
authors = "The Julia Project",
pages = PAGES,
remotes = documenter_stdlib_remotes,
debug = true, # makes makedocs return the Documenter object for use later
)


const known_missing_from_manual = 299

# Check that we're not regressing in missing docs, but only check on PRs so that master builds can still pass
# Only check on Linux 64-bit because the number is platform-dependent
if !in("deploy", ARGS) && Sys.islinux() && Sys.WORD_SIZE == 64
Copy link
Contributor

@mortenpi mortenpi Jul 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe only check the online manual build?

Suggested change
if !in("deploy", ARGS) && Sys.islinux() && Sys.WORD_SIZE == 64
if in("deploy", ARGS)

Copy link
Sponsor Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then PRs would be green and master commits red, and the docs not deployed. We want the opposite

Copy link
Contributor

@mortenpi mortenpi Jul 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also run the doctest CI job on PRs though?

You're right about it breaking the deployment on master though. Is there maybe a Buildkite env variable we can check to see if it's a PR or not?

# ignore logging in the report because makedocs has already run this internally, we just want the number out
missing_from_manual = with_logger(NullLogger()) do
Documenter.missingdocs(doc)
end
if missing_from_manual > known_missing_from_manual
error("""
New docstrings have been added for exported functions that are missing from the manual.
Please add these to the manual.
""")
elseif missing_from_manual < known_missing_from_manual
error("""
Great, the number of missing docstrings in the manual has decreased!
Update `const known_missing_from_manual = $known_missing_from_manual` to $missing_from_manual in `doc/make.jl` to pass this check.
""")
end
end

# Update URLs to external stdlibs (JuliaLang/julia#43199)
for (root, _, files) in walkdir(output_path), file in joinpath.(root, files)
endswith(file, ".html") || continue
Expand Down