Skip to content

docs: render remaining exported docstrings - #4979

Merged
ChrisRackauckas merged 10 commits into
SciML:masterfrom
ChrisRackauckas-Claude:agent/render-missing-public-docs
Aug 17, 2026
Merged

docs: render remaining exported docstrings#4979
ChrisRackauckas merged 10 commits into
SciML:masterfrom
ChrisRackauckas-Claude:agent/render-missing-public-docs

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member

Ignore this PR until it has been reviewed by @ChrisRackauckas.

What changed

This gives every exported docstring reported by strict Documenter a canonical rendered location:

  • the dynamic-optimization API page now owns the collocation and dynamic-problem docs through their declaring ModelingToolkitBase bindings;
  • isinitial, homotopy diagnostics, and the StateSelection matrix helpers are rendered in their relevant manual sections;
  • the two package-module docstrings are rendered on a small package-modules API page.

The four dynamic-problem entries formerly canonicalized on the general problems page moved to the dedicated dynamic-optimization page. Their public documentation remains rendered exactly once.

Failing before

The clean-master strict docs build reported:

12 docstrings not included in the manual:
    ModelingToolkitBase.isinitial :: Tuple{...SymReal}
    ModelingToolkitBase.PyomoCollocation
    ModelingToolkit.ModelingToolkit
    ModelingToolkitBase.NonPolynomialReason
    ModelingToolkitBase.ModelingToolkitBase
    ModelingToolkitBase.InfiniteOptCollocation
    ModelingToolkitBase.CasADiCollocation
    StateSelection.bareiss.bareiss! :: ...
    StateSelection.CLIL.SparseMatrixCLIL
    ModelingToolkitBase.JuMPCollocation
    ModelingToolkitBase.AbstractCollocation
    ModelingToolkitBase.PyomoDynamicOptProblem

A formal bisect of the strict missing-docs gate identified 92c27bb as the first commit that enabled fatal checkdocs = :exports without warning-only handling.

Passing after

On exact upstream f3248317cb51e08e78fb3d1729286905ad61d6d4, I ran:

DISPLAY=:0 JULIA_DEBUG=Documenter xvfb-run -a -s '-screen 0 1024x768x24' \
  julia +lts --startup-file=no --project=docs/ --code-coverage=user docs/make.jl

Documenter emitted no docstrings not included in the manual diagnostic, and :missing_docs disappeared from the terminal error set:

makedocs encountered errors [:docs_block, :cross_references, :linkcheck]

The remaining failures are independent clean-master clusters. The duplicate clusters are isolated in #4977 and #4978. Four invalid StateSelection entries and unresolved links remain under separate investigation. Link checking encountered transient remote failures.

Other local verification

git diff --check
julia +lts --startup-file=no -e 'using Runic; exit(Runic.main(ARGS))' -- --check docs/pages.jl
git diff --no-ext-diff | typos -

These pass. The Julia invocation is used because an unrelated executable named runic shadows Runic.jl on this host.

GROUP=QA julia +lts --startup-file=no --project -e 'using Pkg; Pkg.test()' completed with 38 pass, 4 error. The four errors are the independently reproduced clean-master ExplicitImports checks: no_implicit_imports, no_stale_explicit_imports, all_explicit_imports_via_owners, and all_qualified_accesses_via_owners.

I did not run GPU, downstream, or GROUP=Everything jobs.

Links

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Member Author

Pushed facd7a3e0c973c2d954be6dfc89dbeee833e7544 to fix the Runic indentation failure at docs/make.jl:50 (], aligned to four spaces).

Verification on the pushed tree:

  • /home/crackauc/.juliaup/bin/julia +1.12.4 --project=@runic --startup-file=no -m Runic --check --diff docs/make.jl passed.
  • typos docs/make.jl passed.
  • git diff --check passed.

The standalone docs build was started but stopped after Documenter reported no docs found for ModelingToolkit.StructuralTransformations in docs/src/API/modules.md; this is separate from the Runic fix and remains to investigate.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas
ChrisRackauckas marked this pull request as ready for review August 17, 2026 06:58
@ChrisRackauckas
ChrisRackauckas merged commit be3939a into SciML:master Aug 17, 2026
54 of 68 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants