From 84623d24123cf42271c5130af86ed1c9c727844e Mon Sep 17 00:00:00 2001 From: Carsten Bauer Date: Wed, 31 Jan 2024 18:10:40 +0100 Subject: [PATCH 1/4] documenter init --- .JuliaFormatter.toml | 1 + .github/workflows/documentation.yml | 28 +++++++++++++++++++++++ .gitignore | 3 ++- docs/Project.toml | 7 ++++++ docs/build_docs.jl | 10 +++++++++ docs/make.jl | 35 +++++++++++++++++++++++++++++ docs/src/index.md | 22 ++++++++++++++++++ 7 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 .JuliaFormatter.toml create mode 100644 .github/workflows/documentation.yml create mode 100644 docs/Project.toml create mode 100644 docs/build_docs.jl create mode 100644 docs/make.jl create mode 100644 docs/src/index.md diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml new file mode 100644 index 00000000..453925c3 --- /dev/null +++ b/.JuliaFormatter.toml @@ -0,0 +1 @@ +style = "sciml" \ No newline at end of file diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..8d3572fb --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,28 @@ +name: Documentation + +on: + push: + branches: + - master + tags: '*' + paths: + - 'docs/**' + - 'src/**' + pull_request: + paths: + - 'docs/**' + - 'src/**' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: julia-actions/setup-julia@latest + with: + version: '1' + - name: Build and deploy + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key + run: julia docs/build_docs.jl \ No newline at end of file diff --git a/.gitignore b/.gitignore index 015721cc..24a92613 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +docs/build Manifest.toml .vscode -*~ \ No newline at end of file +*~ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..01424121 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,7 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8" + +[compat] +Documenter = "1.2" +DocumenterTools = "0.1" diff --git a/docs/build_docs.jl b/docs/build_docs.jl new file mode 100644 index 00000000..0d022449 --- /dev/null +++ b/docs/build_docs.jl @@ -0,0 +1,10 @@ +println("--- :julia: Instantiating project") +using Pkg +Pkg.activate("..") +Pkg.instantiate() +Pkg.activate(".") +Pkg.instantiate() +push!(LOAD_PATH, joinpath(@__DIR__, "..")) +deleteat!(LOAD_PATH, 2) +println("+++ :julia: Building documentation") +include("make.jl") diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..b8a8ea71 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,35 @@ +using Documenter +using OhMyThreads + +const ci = get(ENV, "CI", "") == "true" + +@info "Generating Documenter.jl site" +makedocs(; + sitename = "OhMyThreads.jl", + authors = "Carsten Bauer, Mason Protter", + # modules = [OhMyThreads], + checkdocs = :exports, + # doctest = ci, + pages = [ + "OhMyThreads" => "index.md", + # "Examples" => [ + # "A" => "examples/A.md", + # ], + # "Explanations" => [ + # "B" => "explanations/B.md", + # ], + # "References" => [ + # "API" => "references/api.md", + # ], + ], + repo = "https://github.com/JuliaFolds2/OhMyThreads.jl/blob/{commit}{path}#{line}", + format = Documenter.HTML(repolink = "https://github.com/JuliaFolds2/OhMyThreads.jl"; + collapselevel = 1)) + +if ci + @info "Deploying documentation to GitHub" + deploydocs(; + repo = "github.com/JuliaFolds2/OhMyThreads.jl.git", + devbranch = "master", + push_preview = true,) +end diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..d6556ac3 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,22 @@ +# OhMyThreads.jl + +[OhMyThreads.jl](https://github.com/carstenbauer/OhMyThreads.jl/) is meant to be a simple, unambitious package that provides user-friendly ways of doing task-parallel multithreaded calculations via higher-order functions, with a +focus on [data parallelism](https://en.wikipedia.org/wiki/Data_parallelism) without needing to expose julia's +[Task](https://docs.julialang.org/en/v1/base/parallel/) model to users. + +## Installation + +The package is registered. Hence, you can simply use +``` +] add OhMyThreads +``` +to add the package to your Julia environment. + +## Noteworthy Alternatives + +* [ThreadsX.jl](https://github.com/tkf/ThreadsX.jl) +* [Folds.jl](https://github.com/JuliaFolds/Folds.jl) + +## Acknowledgements + +The idea for this package came from [Carsten Bauer](https://github.com/carstenbauer) and [Mason Protter](https://github.com/MasonProtter). Check out the [list of contributors](https://github.com/JuliaFolds2/OhMyThreads.jl/graphs/contributors) for more information. \ No newline at end of file From 862d4317b0c05495712889f9a1b14c2f13b98a8d Mon Sep 17 00:00:00 2001 From: Carsten Bauer Date: Wed, 31 Jan 2024 18:18:54 +0100 Subject: [PATCH 2/4] doc ci fix --- .github/workflows/documentation.yml | 8 ++++++++ docs/build_docs.jl | 1 + 2 files changed, 9 insertions(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 8d3572fb..b8ede42c 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -13,8 +13,16 @@ on: - 'docs/**' - 'src/**' +concurrency: + # Skip intermediate builds: always. + # Cancel intermediate builds: always. + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: build: + permissions: + contents: write runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/docs/build_docs.jl b/docs/build_docs.jl index 0d022449..39868bd1 100644 --- a/docs/build_docs.jl +++ b/docs/build_docs.jl @@ -1,3 +1,4 @@ +cd(@__DIR__) println("--- :julia: Instantiating project") using Pkg Pkg.activate("..") From e8cf9e7d734ebdd3339dbb9ebc2ad8f370840f82 Mon Sep 17 00:00:00 2001 From: Carsten Bauer Date: Wed, 31 Jan 2024 18:43:23 +0100 Subject: [PATCH 3/4] minor --- .github/workflows/documentation.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index b8ede42c..d975ac22 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -23,6 +23,7 @@ jobs: build: permissions: contents: write + statuses: write runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 From ccc413aed927fccaca0b2f38d0f4f77288a37a84 Mon Sep 17 00:00:00 2001 From: Carsten Bauer Date: Wed, 31 Jan 2024 19:52:18 +0100 Subject: [PATCH 4/4] public api etc --- docs/Project.toml | 2 ++ docs/make.jl | 10 ++++++---- docs/src/refs/api.md | 23 +++++++++++++++++++++++ docs/src/refs/internal.md | 18 ++++++++++++++++++ 4 files changed, 49 insertions(+), 4 deletions(-) create mode 100644 docs/src/refs/api.md create mode 100644 docs/src/refs/internal.md diff --git a/docs/Project.toml b/docs/Project.toml index 01424121..623b449b 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,7 +1,9 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8" +StableTasks = "91464d47-22a1-43fe-8b7f-2d57ee82463f" [compat] Documenter = "1.2" DocumenterTools = "0.1" +StableTasks = "0.1.4" \ No newline at end of file diff --git a/docs/make.jl b/docs/make.jl index b8a8ea71..9a9a7209 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,5 +1,6 @@ using Documenter using OhMyThreads +using StableTasks const ci = get(ENV, "CI", "") == "true" @@ -7,7 +8,7 @@ const ci = get(ENV, "CI", "") == "true" makedocs(; sitename = "OhMyThreads.jl", authors = "Carsten Bauer, Mason Protter", - # modules = [OhMyThreads], + modules = [OhMyThreads, StableTasks], checkdocs = :exports, # doctest = ci, pages = [ @@ -18,9 +19,10 @@ makedocs(; # "Explanations" => [ # "B" => "explanations/B.md", # ], - # "References" => [ - # "API" => "references/api.md", - # ], + "References" => [ + "Public API" => "refs/api.md", + "Internal" => "refs/internal.md", + ], ], repo = "https://github.com/JuliaFolds2/OhMyThreads.jl/blob/{commit}{path}#{line}", format = Documenter.HTML(repolink = "https://github.com/JuliaFolds2/OhMyThreads.jl"; diff --git a/docs/src/refs/api.md b/docs/src/refs/api.md new file mode 100644 index 00000000..08ffeab9 --- /dev/null +++ b/docs/src/refs/api.md @@ -0,0 +1,23 @@ +# Public API + +## Index + +```@index +Pages = ["api.md"] +Order = [:function, :macro] +``` + +## Exported + +```@autodocs +Modules = [OhMyThreads] +Private = false +Pages = ["OhMyThreads.jl"] +``` + +## Non-Exported + +```@docs +OhMyThreads.@spawn +OhMyThreads.@spawnat +``` \ No newline at end of file diff --git a/docs/src/refs/internal.md b/docs/src/refs/internal.md new file mode 100644 index 00000000..5a1f7f5f --- /dev/null +++ b/docs/src/refs/internal.md @@ -0,0 +1,18 @@ +# Internal + +**The following is internal, i.e. not public API, and might change at any point.** + +## Index + +```@index +Pages = ["internal.md"] +Order = [:function, :macro] +``` + +## References + +```@autodocs +Modules = [OhMyThreads, OhMyThreads.Tools] +Public = false +Pages = ["OhMyThreads.jl", "tools.jl"] +```