Skip to content

Document exported public API#221

Merged
ChrisRackauckas merged 1 commit into
SciML:mainfrom
ChrisRackauckas-Claude:codex/public-api-docs-audit
Jul 8, 2026
Merged

Document exported public API#221
ChrisRackauckas merged 1 commit into
SciML:mainfrom
ChrisRackauckas-Claude:codex/public-api-docs-audit

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor

Summary

This PR audits the exported public API and tightens the rendered documentation coverage. Please ignore this PR until reviewed by @ChrisRackauckas.

Changes:

  • Adds rendered API coverage for the exported DEQs alias.
  • Moves/expands the DeepEquilibriumNetwork docstring to the exported type definition point.
  • Expands exported constructor/type docstrings with signatures, arguments, returns, and examples where appropriate.

Verification

Ran locally with Julia 1.10 using timeout 3600:

  • timeout 3600 /home/crackauc/.juliaup/bin/julia +1.10 --project=@runic -e 'using Runic; exit(Runic.main(["--check", "."]))'\n - passed with exit code 0\n- Export audit one-liner over names(DeepEquilibriumNetworks; all=false)\n - exported=[:DEQs, :DeepEquilibriumNetwork, :DeepEquilibriumSolution, :MultiScaleDeepEquilibriumNetwork, :MultiScaleNeuralODE, :MultiScaleSkipDeepEquilibriumNetwork, :SkipDeepEquilibriumNetwork]\n - undocumented=Symbol[]\n - missing_api=Symbol[]\n- timeout 3600 /home/crackauc/.juliaup/bin/julia +1.10 --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); include("docs/make.jl")'\n - passed with exit code 0\n - warnings observed: existing arXiv HTTP-to-HTTPS link redirects, existing large generated HTML warning for tutorials/basic_mnist_deq.md, and skipped deployment outside CI\n- timeout 3600 /home/crackauc/.juliaup/bin/julia +1.10 --project=. -e 'using Pkg; Pkg.test()'\n - passed\n - Utils Tests | 13 pass\n - Layers Tests | 1538 pass\n

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
@ChrisRackauckas-Claude ChrisRackauckas-Claude force-pushed the codex/public-api-docs-audit branch from 87f02d0 to ce48aa5 Compare July 8, 2026 11:56
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor Author

Addressed the review on the DEQs handling.

Changes in the updated push:

  • Removed the @doc ... DeepEquilibriumNetworks module-binding workaround from src/DeepEquilibriumNetworks.jl.
  • Kept DEQs covered in rendered API docs as prose rather than adding a misleading source-site docstring for the module binding. A clean source docstring on const DEQs = DeepEquilibriumNetworks creates a module-valued binding that Documenter normalizes away during canonical missing-doc checks, which is why the previous workaround was noisy.
  • Fixed the new SkipDeepEquilibriumNetwork doctest example to use a tuple-compatible Parallel(+, Dense, Dense) model; the previous bare Dense example caused the QA doctest failure on CI.
  • Cleaned generated docs assets before commit.

Rerun locally with timeout 3600:

  • Runic check: passed.
  • Export/API audit: all exports appear in docs/src/api.md; all non-alias exported bindings have source doc metadata; DEQs is explicitly handled as the module alias exception in rendered API prose.
  • Docs build (julia +1.10 --project=docs -e ... include("docs/make.jl")): passed with only existing link redirect / HTML size / skipped deployment warnings.
  • QA + doctests on Julia 1.12 (julia +1.12 --project=test/qa -e ... include("test/qa/qa.jl")): passed, including doctests.

@ChrisRackauckas ChrisRackauckas marked this pull request as ready for review July 8, 2026 11:58
@ChrisRackauckas ChrisRackauckas merged commit 15f00d6 into SciML:main Jul 8, 2026
9 of 10 checks passed
@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor Author

Follow-up after the review note: the branch now removes the module-level @doc ... DeepEquilibriumNetworks workaround entirely. DEQs is handled as a rendered API prose entry for the exported module alias, while the remaining exported user-facing API has source-site docstrings and @docs coverage. Generated docs assets were cleaned before the amended commit.\n\nRelevant local checks rerun after this update:\n- timeout 3600 julia +1.10 --project=@runic -e 'using Runic; exit(Runic.main(["--check", "."]))'\n- export/API audit script under julia +1.10 --project=.\n- timeout 3600 julia +1.10 --project=docs -e 'using Pkg; Pkg.instantiate(); include("docs/make.jl")'\n- timeout 3600 julia +1.12 --project=test/qa -e 'using Pkg; Pkg.instantiate(); include("test/qa/qa.jl")'\n\nThe PR GPU failure reproduces on main and is tracked separately in #222.

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