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.