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..d975ac22 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,37 @@ +name: Documentation + +on: + push: + branches: + - master + tags: '*' + paths: + - 'docs/**' + - 'src/**' + pull_request: + paths: + - '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 + statuses: write + 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..623b449b --- /dev/null +++ b/docs/Project.toml @@ -0,0 +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/build_docs.jl b/docs/build_docs.jl new file mode 100644 index 00000000..39868bd1 --- /dev/null +++ b/docs/build_docs.jl @@ -0,0 +1,11 @@ +cd(@__DIR__) +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..9a9a7209 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,37 @@ +using Documenter +using OhMyThreads +using StableTasks + +const ci = get(ENV, "CI", "") == "true" + +@info "Generating Documenter.jl site" +makedocs(; + sitename = "OhMyThreads.jl", + authors = "Carsten Bauer, Mason Protter", + modules = [OhMyThreads, StableTasks], + checkdocs = :exports, + # doctest = ci, + pages = [ + "OhMyThreads" => "index.md", + # "Examples" => [ + # "A" => "examples/A.md", + # ], + # "Explanations" => [ + # "B" => "explanations/B.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"; + 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 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"] +```