Skip to content

Remove stale structural-transformation internals from strict docs #4943

Description

@ChrisRackauckas-Claude

Summary

The exact documentation build on current master reports 31 errors from
docs/src/internals/structural_transformation.md:

  • 28 undefined bindings;
  • no docstrings for find_solvables! and TearingState; and
  • one dangling pantelides! cross-reference from the rendered
    dae_index_lowering docstring.

The page documents internal implementation names that were removed from or moved out of
ModelingToolkit. Re-exporting or qualifying those dependency internals would expand the
public dependency surface; the focused fix is to remove the stale entries and replace the
dangling pantelides! link with plain prose.

Reproduction

Tested at 92c27bb9fdcaa024ff190feb3d665452e33f9bd8 with Julia 1.12.6 on Linux x86_64:

/home/crackauc/.juliaup/bin/julia +release --project=docs --startup-file=no \
  -e 'using Pkg; Pkg.instantiate()'
/home/crackauc/.juliaup/bin/julia +release --project=docs --startup-file=no docs/make.jl

The second command exited 1. A local log aggregate found:

structural undefined=28
structural no_docs=2
structural crossrefs=1
all undefined=58
ERROR: LoadError: `makedocs` encountered errors [:docs_block, :missing_docs, :cross_references, :linkcheck]

The 28 undefined names are:

InducedCondensationGraph
MatchedCondensationGraph
Matching
SystemStructure
TransformationState
Unassigned
algeqs
algvars_range
check_consistency
computed_highest_diff_variables
dervars_range
diffvars_range
distribute_shift
get_fullvars
is_only_discrete
isalgvar
isdervar
isdiffeq
isdiffvar
linear_subsys_adjmat!
lower_shift_varname
pantelides!
shift2term
simplify_shifts
system_subset
tearing_reassemble
torn_system_jacobian_sparsity
unassigned

History

There are two relevant boundaries:

  1. A representative source-content bisect for the removed isalgvar export used:

    git bisect start upstream/master ad3cd801ba70394adc6e950cc87a3318faf5ac03
    git bisect run bash -c 'git grep -Eq "export .*isalgvar" -- src && exit 0; exit 1'

    The first bad commit is fce566c46279c8945ed385f3ab7272cc17247b2c. It moved structural
    state-selection implementation into dependency packages but left this documentation
    page's blob unchanged from its parent.

  2. The current hard-failure boundary is
    92c27bb9fdcaa024ff190feb3d665452e33f9bd8. Its parent kept
    [:docs_block, :missing_docs, :cross_references] in Documenter's warnonly; this commit
    removed that setting and exposed the pre-existing stale page as a hard failure.

Focused fix proof

I tested an uncommitted, deletion-only focused patch:

  • remove the 28 undefined entries and the two non-owned/no-docstring entries from the page;
  • remove the headings made empty by those deletions; and
  • change [`pantelides!`](@ref) in dae_index_lowering to plain "internal Pantelides pass"
    prose.

The same full docs command then produced:

structural undefined=0
structural no_docs=0
structural crossrefs=0
all undefined=30

The full command still exited 1 on unrelated current-master docs errors in
bipartite_graph.md, API/model_building.md, API/problems.md, API/variables.md, and
other independent cross-references. I therefore did not push a first PR that is known to
fail the repository's required full-docs gate.

Additional local checks on the focused diff:

julia +release --startup-file=no -m Runic --check .     exit 0
typos docs/src/internals/structural_transformation.md \
  src/structural_transformation/pantelides.jl           exit 0
git diff --check                                         exit 0

Current-registry GROUP=QA completed with the independently tracked master result:
20 passed, 3 failed, 2 errored. The failures are JET, two ExplicitImports parser errors,
the undocumented StructuralTransformations module, and the unapproved
generate_trajectory re-export; they are unchanged by this docs-only fix and are tracked
separately.

Links

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions