Skip to content

Commit ca15026

Browse files
giordanoclaude
giordano
and
claude
authored
Add Documenter.jl documentation (#74)
* Add Documenter.jl documentation Co-authored-by: Claude <[email protected]> * Add workflow for deploying the docs * Some fixes and move information from README to the docs * More tips * Remove non-sense * Remove custom output streams section * Remove redundant section about custom workers * Min fixes * Fix sectioning level * Simplify docs deploy job * Fix syntax highlighting? * Add workflow for cleaning up previews on schedule * Tweak query of packages using PTR * Clarify filtering is on test files, not testsets * Load balance parentheses * Add more cross-references in docstrings * Clarify once again filtering is on test files, not testsets * Update load balancing strategy in docstring --------- Co-authored-by: Claude <[email protected]>
1 parent 19cd147 commit ca15026

File tree

11 files changed

+598
-102
lines changed

11 files changed

+598
-102
lines changed

‎.github/workflows/DocPreviewsCleanup.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Doc Previews Cleanup
2+
3+
on:
4+
schedule:
5+
- cron: "25 22 * * 2"
6+
workflow_dispatch:
7+
8+
concurrency:
9+
# Same group concurrency as the `Documentation.yml` workflow, because they both
10+
# git-push to the same branch, so we want to avoid clashes.
11+
group: docs-pushing
12+
13+
jobs:
14+
doc-preview-cleanup:
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: write
18+
steps:
19+
- name: Checkout gh-pages branch
20+
uses: actions/checkout@v6
21+
with:
22+
ref: gh-pages
23+
- name: Delete preview and history + push changes
24+
run: |
25+
if [[ -d previews ]]; then
26+
git config user.name "${{github.actor}}"
27+
git config user.email "${{github.actor_id}}+${{github.actor}}@users.noreply.github.com"
28+
git rm -rf previews/
29+
git commit -m 'Delete previews directory'
30+
git branch gh-pages-new $(echo "Delete history" | git commit-tree HEAD^{tree})
31+
git push --force-with-lease origin gh-pages-new:gh-pages
32+
fi

‎.github/workflows/Documentation.yml‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
tags: "*"
8+
paths:
9+
- ".github/workflows/Documentation.yml"
10+
- "docs/**"
11+
- "src/**"
12+
- "Project.toml"
13+
pull_request:
14+
paths:
15+
- ".github/workflows/Documentation.yml"
16+
- "docs/**"
17+
- "src/**"
18+
- "Project.toml"
19+
release:
20+
21+
concurrency:
22+
# Skip intermediate builds: always.
23+
# Cancel intermediate builds: always.
24+
group: ${{ github.workflow }}-${{ github.ref }}
25+
cancel-in-progress: true
26+
27+
jobs:
28+
build-docs:
29+
permissions:
30+
actions: write
31+
contents: write
32+
pull-requests: read
33+
statuses: write
34+
runs-on: ubuntu-latest
35+
timeout-minutes: 30
36+
steps:
37+
- uses: actions/checkout@v6
38+
- uses: julia-actions/setup-julia@v2
39+
with:
40+
version: "1"
41+
- uses: julia-actions/cache@v2
42+
id: julia-cache
43+
with:
44+
cache-name: Documentation
45+
- name: Instantiate docs environment
46+
shell: julia --color=yes --project=docs {0}
47+
run: |
48+
using Pkg
49+
Pkg.instantiate()
50+
- name: Build documentation
51+
run:
52+
julia --color=yes --project=docs docs/make.jl
53+
env:
54+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
55+
- name: Save Julia depot cache on cancel or failure
56+
id: julia-cache-save
57+
if: cancelled() || failure()
58+
uses: actions/cache/save@v4
59+
with:
60+
path: |
61+
${{ steps.julia-cache.outputs.cache-paths }}
62+
key: ${{ steps.julia-cache.outputs.cache-key }}
63+
- uses: actions/upload-artifact@v5
64+
with:
65+
name: documentation-build
66+
path: docs/build
67+
retention-days: 10
68+
69+
deploy-docs:
70+
# Deploy docs only if triggers is not a PR, or a PR not from a fork.
71+
if: ${{ (github.event_name != 'pull_request') || (! github.event.pull_request.head.repo.fork) }}
72+
needs: build-docs
73+
permissions:
74+
actions: write
75+
contents: write
76+
pull-requests: read
77+
statuses: write
78+
runs-on: ubuntu-latest
79+
timeout-minutes: 30
80+
concurrency:
81+
# Have only one job pushing the docs at a time.
82+
group: docs-pushing
83+
steps:
84+
- uses: actions/checkout@v6
85+
- uses: julia-actions/setup-julia@v2
86+
with:
87+
version: "1"
88+
- uses: julia-actions/cache@v2
89+
with:
90+
# Steal cache from the build job
91+
cache-name: Documentation
92+
- uses: actions/download-artifact@v6
93+
with:
94+
name: documentation-build
95+
path: docs/build
96+
- name: Instantiate docs environment
97+
shell: julia --color=yes {0}
98+
run: |
99+
# We only need `Documenter` for publishing the docs, let's not
100+
# reinstall the world all over again.
101+
using Pkg
102+
Pkg.add(; name="Documenter", version="1")
103+
- name: Deploy documentation
104+
run:
105+
julia --color=yes docs/deploy.jl
106+
env:
107+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
108+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
Manifest.toml
1+
Manifest.toml
2+
/docs/build/

‎README.md‎

Lines changed: 5 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# ParallelTestRunner.jl
22

3+
[![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliatesting.github.io/ParallelTestRunner.jl/)
4+
[![Latest Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://juliatesting.github.io/ParallelTestRunner.jl/dev)
5+
36
Simple parallel test runner for Julia tests with autodiscovery.
47

58
## Usage
@@ -40,102 +43,9 @@ using ParallelTestRunner
4043
runtests(MyModule, ARGS)
4144
```
4245

43-
### Customizing the test suite
44-
45-
By default, `runtests` automatically discovers all `.jl` files in your `test/` directory (excluding `runtests.jl` itself) using the `find_tests` function. You can customize which tests to run by providing a custom `testsuite` dictionary:
46-
47-
```julia
48-
# Manually define your test suite
49-
testsuite = Dict(
50-
"basic" => quote
51-
include("basic.jl")
52-
end,
53-
"advanced" => quote
54-
include("advanced.jl")
55-
end
56-
)
57-
58-
runtests(MyModule, ARGS; testsuite)
59-
```
60-
61-
You can also use `find_tests` to automatically discover tests and then filter or modify them. This requires manually parsing arguments so that filtering is only applied when the user did not request specific tests to run:
62-
63-
```julia
64-
# Start with autodiscovered tests
65-
testsuite = find_tests(pwd())
66-
67-
# Parse arguments
68-
args = parse_args(ARGS)
69-
70-
if filter_tests!(testsuite, args)
71-
# Remove tests that shouldn't run on Windows
72-
if Sys.iswindows()
73-
delete!(testsuite, "ext/specialfunctions")
74-
end
75-
end
76-
77-
runtests(MyModule, args; testsuite)
78-
```
79-
80-
### Provide defaults
81-
82-
`runtests` takes a keyword argument that one can use to provide default definitions to be loaded before each testfile.
83-
As an example one could always load `Test` and the package under test.
84-
85-
```julia
86-
const init_code = quote
87-
using Test
88-
using MyPackage
89-
end
90-
91-
runtests(MyModule, ARGS; init_code)
92-
```
93-
94-
### Interactive use
95-
96-
Arguments can also be passed via the standard `Pkg.test` interface for interactive control. For example, here is how we could run the subset of tests that start with the testset name "MyTestsetA" in i) verbose mode, and ii) with default threading enabled:
97-
98-
```julia-repl
99-
# In an environment where `MyPackage.jl` is available
100-
julia --proj
101-
102-
julia> using Pkg
103-
104-
# No need to start a fresh session to change threading
105-
julia> Pkg.test("MyModule"; test_args=`--verbose MyTestsetA`, julia_args=`--threads=auto`);
106-
```
107-
Alternatively, arguments can be passed directly from the command line with a shell alias like the one below:
108-
109-
```julia-repl
110-
jltest --threads=auto -- --verbose MyTestsetA
111-
```
112-
113-
<details><summary>Shell alias</summary>
114-
115-
```shell
116-
function jltest {
117-
julia=(julia)
118-
119-
# certain arguments (like those beginnning with a +) need to come first
120-
if [[ $# -gt 0 && "$1" = +* ]]; then
121-
julia+=("$1")
122-
shift
123-
fi
124-
125-
"${julia[@]}" --startup-file=no --project -e "using Pkg; Pkg.API.test(; test_args=ARGS)" "$@"
126-
}
127-
```
128-
129-
</details>
130-
131-
## Packages using ParallelTestRunner.jl
132-
133-
There are a few packages already using `ParallelTestRunner.jl` to parallelize their tests, you can look at their setups if you need inspiration to move your packages as well:
46+
## Documentation
13447

135-
* [`Enzyme.jl`](https://github.com/EnzymeAD/Enzyme.jl/blob/main/test/runtests.jl)
136-
* [`GPUArrays.jl`](https://github.com/JuliaGPU/GPUArrays.jl/blob/master/test/runtests.jl)
137-
* [`GPUCompiler.jl`](https://github.com/JuliaGPU/GPUCompiler.jl/blob/master/test/runtests.jl)
138-
* [`Metal.jl`](https://github.com/JuliaGPU/Metal.jl/blob/main/test/runtests.jl)
48+
For more details about the use of this package, read the [documentation](https://juliatesting.github.io/ParallelTestRunner.jl/).
13949

14050
## Inspiration
14151
Based on [@maleadt](https://github.com/maleadt) test infrastructure for [CUDA.jl](https://github.com/JuliaGPU/CUDA.jl).

‎docs/Project.toml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
ParallelTestRunner = "d3525ed8-44d0-4b2c-a655-542cee43accc"
4+
5+
[compat]
6+
Documenter = "1"
7+
8+
[sources]
9+
ParallelTestRunner = {path = ".."}

‎docs/deploy.jl‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
using Documenter
2+
3+
deploydocs(;
4+
repo="github.com/JuliaTesting/ParallelTestRunner.jl",
5+
devbranch="main",
6+
# Only push previews if all the relevant environment variables are non-empty. This is an
7+
# attempt to work around https://github.com/JuliaDocs/Documenter.jl/issues/2048.
8+
push_preview = all(!isempty, (get(ENV, "GITHUB_TOKEN", ""), get(ENV, "DOCUMENTER_KEY", ""))),
9+
)

‎docs/make.jl‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
using Documenter
2+
using ParallelTestRunner
3+
4+
makedocs(;
5+
modules=[ParallelTestRunner],
6+
authors="Valentin Churavy <[email protected]> and contributors",
7+
repo="https://github.com/JuliaTesting/ParallelTestRunner.jl/blob/{commit}{path}#{line}",
8+
sitename="ParallelTestRunner.jl",
9+
format=Documenter.HTML(;
10+
prettyurls=get(ENV, "CI", "false") == "true",
11+
canonical="https://juliatesting.github.io/ParallelTestRunner.jl",
12+
assets=String[],
13+
),
14+
pages=[
15+
"Home" => "index.md",
16+
"Advanced Usage" => "advanced.md",
17+
"API Reference" => "api.md",
18+
],
19+
)

0 commit comments

Comments
 (0)