Skip to content

Document public callback API examples#322

Draft
ChrisRackauckas-Claude wants to merge 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:docs/public-api-full-audit
Draft

Document public callback API examples#322
ChrisRackauckas-Claude wants to merge 1 commit into
SciML:masterfrom
ChrisRackauckas-Claude:docs/public-api-full-audit

Conversation

@ChrisRackauckas-Claude

Copy link
Copy Markdown
Contributor

This draft PR should be ignored until reviewed by @ChrisRackauckas.

Summary

  • Adds usage examples and return sections to user-facing public callback API docstrings.
  • Moves remaining public constructor docs off @doc doc""" attachments and onto the definitions directly.
  • Adds a QA test that every exported public name has a docstring and appears in a rendered @docs block.
  • Removes the now-stale Markdown.@doc_str import.

Validation

  • timeout 3600 /home/crackauc/.juliaup/bin/julia +release --project=test/qa -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); include("test/qa/qa.jl")' passed: Quality Assurance 17/17; Public API documentation coverage 3/3.\n- timeout 3600 /home/crackauc/.juliaup/bin/julia +release --project=. -e 'using Pkg; Pkg.test()' passed.\n- Runic v1.7.0 run with --inplace on touched Julia files.\n- git diff --check passed.\n\n## Docs Build Note\n- Full docs command timeout 3600 /home/crackauc/.juliaup/bin/julia +release --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); include("docs/make.jl")' timed out after one hour during Documenter.HTMLWriter.render. Documenter had already completed ExpandTemplates, CrossReferences, and CheckDocument; the timeout stack was in HTML rendering/data-file hashing while rendering existing uncertainty plot assets. I am not marking full docs as passed.

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

Copy link
Copy Markdown
Contributor Author

CI note after opening this draft:

  • tests / AD (julia 1, ubuntu-latest) failed before reaching DiffEqCallbacks assertions. The job fails while precompiling SciMLSensitivity, from SciMLBaseFunctionPropertiesExt with UndefVarError: islinear not defined in FunctionProperties. This looks like dependency resolution / upstream compatibility, not code touched by this PR.
  • Local validation that completed before opening the PR remains:
    • QA: Quality Assurance 17/17; Public API documentation coverage 3/3.
    • Full local Pkg.test() passed.
    • Runic v1.7.0 --inplace on touched files.
    • Full docs build timed out after one hour during Documenter.HTMLWriter.render; see PR body for details.

I attempted to invoke the local AD group with Pkg.test(; test_args=["AD"]), but this repository invocation selected Core tests instead, so I stopped that duplicate run and am not counting it as validation.

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