Upgrade docs to Documenter 1 - #255
Merged
Merged
Conversation
Documenter 1 turns missing docstrings and unused footnotes into hard errors, so the build had to be fixed alongside the version bump: - Document the 13 docstrings that were missing from the manual: the CCA significance tests, `invsqrtm`, `coefnames`, and the generic methods defined on the abstract model types, plus a section in the development page for the internal helpers. - Cite the four footnotes that were defined but never referenced. - Spell the `predict(::MDS, ::AbstractVector)` signature the way the method is actually defined, so it registers as documented. Also fix four `@math` blocks that should have been `math` blocks, left over from the Sphinx conversion, and a copy-pasted signature line in the `coefnames` docstring. Drop the `Base.HOME_PROJECT` workaround, which Documenter no longer needs, and set the canonical URL.
`coefnames` was defined as a package-local function rather than a method on the StatsAPI generic, so it was invisible to consumers going through StatsAPI or StatsBase. Import it alongside the other StatsAPI functions we extend. StatsAPI has exported it since 1.3, our compat floor, so no bound needs to change. `invsqrtm` was also listed twice in the export block.
`docs/source` and the Sphinx `Makefile` were superseded by the Documenter sources in `docs/src` and are no longer built or referenced.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Supersedes #250, which bumped the Documenter bound but left the build failing.
Documenter 1 turns missing docstrings and unused footnotes into hard errors, so the docs had to be fixed alongside the version bump:
checkdocs: the three CCA significance tests (cca.md),invsqrtm(whiten.md),coefnames(lda.md), and the generic methods on the abstract model types under a new Generic Interface section inapi.md, withcalcscattermat/toindices/L2distanceunder Internals.cca.md[^1],fa.md[^2]/[^3],lreg.md[^1]. Each now has a citation point in the prose.Pre-existing problems fixed along the way:
```@mathblocks. That is not a Documenter expander, so the math had never rendered — leftovers from the Sphinx conversion. They are```mathnow.mds.mddeclaredpredict(::MDS, ::AbstractVector{<:Real}), but the method ispredict(::MDS{T}, ::AbstractVector). Loose enough to resolve, not exact enough to count as documented.coefnamesdocstring header saidcoef(f::LinearDiscriminant).coefnameswas a package-local function rather than a method on the StatsAPI generic, so it was invisible to consumers reaching it through StatsAPI or StatsBase. StatsAPI has exported it since 1.3, the existing compat floor, so no bound changes.invsqrtmwas exported twice.Base.HOME_PROJECTworkaround, which Documenter no longer needs, and setcanonical.docs/sourceand the SphinxMakefile, superseded bydocs/srcand no longer built or referenced.Verified locally:
docs/make.jlexits 0 with only the benign SVG-fallback and no-deploy-detected warnings, and the test suite passes.