Merge pull request #1 from CliMA/dy/docs

Add a documentation page

.github/workflows/DocCleanup.yml

@@ -0,0 +1,28 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+
+      - name: Delete preview and history
+        run: |
+            git config user.name "Documenter.jl"
+            git config user.email "documenter@juliadocs.github.io"
+            git rm -rf "previews/PR$PRNUM"
+            git commit -m "delete preview"
+            git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+        env:
+            PRNUM: ${{ github.event.number }}
+
+      - name: Push changes
+        run: |
+            git push --force origin gh-pages-new:gh-pages

.github/workflows/Documentation.yml

@@ -0,0 +1,28 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docbuild:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.10'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - 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 --project=docs/ docs/make.jl

README.md

@@ -1,7 +1,22 @@
-# BroadcastFusion.jl
+# FusibleBroadcasts.jl
 
 An experimental framework for fusing broadcast expressions across arbitrary language constructs (functions, loops, conditionals, and so on). This package is being developed with the goal of minimizing kernel launch cost in `ClimaAtmos.jl`, whose source code contains hundreds of broadcast expressions that could potentially be fused into a much smaller number of kernel launches.
 
-This package exports two macros:
-- `@lazy_dot`: An analogue to `@.` that executes calls to `Base.broadcasted` but drops the final call to `Base.materialize`. This macro be used to split long broadcast expressions into meaningful sub-expressions without sacrificing performance.
-- `@fusible`: An annotation that can be added to method definitions, allowing them to participate in the process of broadcast fusion. As long as the method body satisfies several syntactic constraints, this macro can generate an alternative method definition in which all calls to `Base.materialize!` are replaced with calls to `fused_materialize!`, which stores the output of `@lazy_dot` so that it can later be evaluated in an optimally fused way.
+|||
+|---------------------:|:----------------------------------------------|
+| **Documentation**    | [![dev][docs-dev-img]][docs-dev-url]          |
+| **Docs Build**       | [![docs build][docs-bld-img]][docs-bld-url]   |
+| **GHA CI**           | [![gha ci][gha-ci-img]][gha-ci-url]           |
+| **Code Coverage**    | [![codecov][codecov-img]][codecov-url]        |
+
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://CliMA.github.io/FusibleBroadcasts.jl/dev/
+
+[docs-bld-img]: https://github.com/CliMA/FusibleBroadcasts.jl/actions/workflows/Documentation.yml/badge.svg
+[docs-bld-url]: https://github.com/CliMA/FusibleBroadcasts.jl/actions/workflows/Documentation.yml
+
+[gha-ci-img]: https://github.com/CliMA/FusibleBroadcasts.jl/actions/workflows/ci.yml/badge.svg
+[gha-ci-url]: https://github.com/CliMA/FusibleBroadcasts.jl/actions/workflows/ci.yml
+
+[codecov-img]: https://codecov.io/gh/CliMA/FusibleBroadcasts.jl/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/CliMA/FusibleBroadcasts.jl

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,16 @@
+using Documenter
+using FusibleBroadcasts
+
+makedocs(;
+    sitename = "FusibleBroadcasts.jl",
+    modules = [FusibleBroadcasts],
+    pages = ["Home" => "index.md", "API" => "api.md"],
+    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
+)
+
+deploydocs(
+    repo = "github.com/CliMA/FusibleBroadcasts.jl.git",
+    devbranch = "main",
+    push_preview = true,
+    forcepush = true,
+)

docs/src/api.md

@@ -0,0 +1,6 @@
+# API
+
+```@autodocs
+Modules = [FusibleBroadcasts]
+Order   = [:macro, :type, :function]
+```

docs/src/index.md

@@ -0,0 +1,5 @@
+#  FusibleBroadcasts.jl
+
+An experimental framework for fusing broadcast expressions across arbitrary language constructs. This package exports two macros:
+- `@lazy_dot`: An analogue to `@.` that executes calls to `Base.broadcasted` but drops the final call to `Base.materialize`. This macro be used to split long broadcast expressions into meaningful sub-expressions without sacrificing performance.
+- `@fusible`: An annotation that can be added to method definitions, allowing them to participate in the process of broadcast fusion. As long as the method body satisfies several syntactic constraints, this macro can generate an alternative method definition where all calls to `Base.materialize!` are replaced with calls to `fused_materialize!`, which stores the output of `@lazy_dot` so that it can later be evaluated in an optimally fused way. *Note: This macro is still in an early stage of development. Use with caution.*

test/lazy_dot.jl

@@ -28,7 +28,6 @@ end
     @test_throws "broadcastable" @macroexpand @lazy_dot foo(a) = 1
     @test_throws "broadcastable" @macroexpand @lazy_dot true ? 1 : 2
     @test_throws "broadcastable" @macroexpand @lazy_dot for i in 1:2
-        nothing
     end
 
     @test_throws "assignment" @macroexpand @lazy_dot a = 1 + 2