From e9f38d47e06c361333aef86f7bac58a1d9859362 Mon Sep 17 00:00:00 2001 From: ChrisRackauckas-Claude Date: Thu, 17 Sep 2026 22:00:48 -0400 Subject: [PATCH] ci: add Documentation workflow and build the existing docs sources The repo already had `docs/src/api.md` but no `docs/make.jl`, no docs environment and no workflow, so the API reference was never built or rendered. Adds the missing docs environment, a home page that renders the package docstring and usage, and the standard reusable Documentation workflow including the token permissions the reusable requires (cf. SciML/DataCollocations.jl#54). Each public name is rendered exactly once: the module docstring on the home page and the exported helpers on the API page, so Documenter's duplicate-docs check passes. Verified with a full local docs build (zero errors). Co-Authored-By: Chris Rackauckas Agent-Harness: OpenCode Agent-Model: muse-spark-1.3-contributor-free Agent-Session: local session at /home/crackauc/sandbox/tmp_20260917_040834_91074 (no public conversation URL) --- .github/workflows/Documentation.yml | 27 +++++++++++++++++++++++++++ docs/Project.toml | 8 ++++++++ docs/make.jl | 20 ++++++++++++++++++++ docs/src/api.md | 28 ++++++++++++++++++++++++++-- docs/src/index.md | 28 ++++++++++++++++++++++++++++ 5 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/Documentation.yml create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/index.md diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml new file mode 100644 index 0000000..b32eb49 --- /dev/null +++ b/.github/workflows/Documentation.yml @@ -0,0 +1,27 @@ +name: Documentation + +on: + push: + branches: + - main + tags: '*' + pull_request: + +# The reusable documentation workflow requests these permissions for its +# build job; declare them here so the call starts even when the repo's +# default GITHUB_TOKEN permissions are read-only. +permissions: + actions: write + contents: write + pull-requests: write + statuses: write + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }} + +jobs: + build-and-deploy-docs: + name: "Documentation" + uses: "SciML/.github/.github/workflows/documentation.yml@v1" + secrets: "inherit" diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..e88887d --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,8 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +SciMLTesting = "09d9d899-5365-40a9-917a-5f67fddea283" + +[compat] +Documenter = "1" +SciMLTesting = "2" +julia = "1.10" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..c629544 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,20 @@ +using Documenter +using SciMLTesting + +makedocs(; + modules = [SciMLTesting], + authors = "SciML Contributors", + sitename = "SciMLTesting.jl", + format = Documenter.HTML(; + prettyurls = get(ENV, "CI", "false") == "true", + canonical = "https://docs.sciml.ai/SciMLTesting/stable/", + ), + pages = [ + "Home" => "index.md", + "API" => "api.md", + ], +) + +deploydocs(; + repo = "github.com/SciML/SciMLTesting.jl.git", +) diff --git a/docs/src/api.md b/docs/src/api.md index 8f518ff..7655519 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -1,5 +1,29 @@ # API Reference -```@autodocs -Modules = [SciMLTesting] +## Test dispatch + +```@docs +read_test_groups +current_group +detect_sublibrary_group +run_tests +run_everything +``` + +## Test environments + +```@docs +activate_group_env +develop_sources! +with_clean_persistent_tasks_sources +``` + +## Quality assurance + +```@docs +run_qa +run_explicit_imports +run_api_docs +public_api_names +public_reexports ``` diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..dde6628 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,28 @@ +# SciMLTesting.jl + +```@docs +SciMLTesting +``` + +## Usage + +A package's `test/runtests.jl` replaces its hand-written `GROUP` ladder with a +single call to [`run_tests`](@ref): + +```julia +using SciMLTesting + +run_tests() +``` + +The groups a package supports are declared in `test/test_groups.toml`. A group +that has its own environment can be selected by name through the `GROUP` +environment variable, which is what CI lanes use: + +```sh +GROUP=Core julia --project -e 'using Pkg; Pkg.test()' +``` + +## API + +See the [API Reference](@ref) for the full list of exported helpers.