From 12b4ae6583aa56279d0b2f5925cdb37060b11f35 Mon Sep 17 00:00:00 2001 From: Dennis Yatunin Date: Tue, 2 Apr 2024 17:27:41 -0700 Subject: [PATCH] Add a documentation page --- .github/workflows/DocCleanup.yml | 28 ++++++++++++++++++++++++++++ .github/workflows/Documentation.yml | 28 ++++++++++++++++++++++++++++ README.md | 23 +++++++++++++++++++---- docs/Project.toml | 2 ++ docs/make.jl | 16 ++++++++++++++++ docs/src/api.md | 6 ++++++ docs/src/index.md | 5 +++++ test/lazy_dot.jl | 1 - 8 files changed, 104 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/DocCleanup.yml create mode 100644 .github/workflows/Documentation.yml create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/api.md create mode 100644 docs/src/index.md diff --git a/.github/workflows/DocCleanup.yml b/.github/workflows/DocCleanup.yml new file mode 100644 index 0000000..43b39af --- /dev/null +++ b/.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 diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml new file mode 100644 index 0000000..b14eea5 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 76032e3..cce7439 100644 --- a/README.md +++ b/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 diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..dfa65cd --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,2 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..98f91b7 --- /dev/null +++ b/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, +) diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 0000000..6474e75 --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,6 @@ +# API + +```@autodocs +Modules = [FusibleBroadcasts] +Order = [:macro, :type, :function] +``` diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..86d4919 --- /dev/null +++ b/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.*** diff --git a/test/lazy_dot.jl b/test/lazy_dot.jl index 71d4d7c..43b6cb5 100644 --- a/test/lazy_dot.jl +++ b/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