Merge pull request #18 from JuliaFolds2/cb/docs

Set up Documenter

.JuliaFormatter.toml

@@ -0,0 +1 @@
+style = "sciml"

.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

.gitignore

@@ -1,3 +1,4 @@
+docs/build
 Manifest.toml
 .vscode
-*~
+*~

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"

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")

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

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.

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
+```

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"]
+```