unify known limitations into one page

.github/workflows/CI.yml

@@ -12,6 +12,11 @@ concurrency:
   # Cancel intermediate builds: only if it is a pull request build.
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+permissions:
+  contents: write
+  pull-requests: write
+
 jobs:
   test:
     name: ${{ matrix.test_group }}-${{ matrix.version }}-${{ matrix.arch }}
@@ -186,17 +191,27 @@ jobs:
             cat bench/benchmark_results.txt
             echo "EOF"
           } >> $GITHUB_OUTPUT
+
       - name: Find Comment
         uses: peter-evans/find-comment@v3
         id: fc
         with:
           issue-number: ${{ github.event.pull_request.number }}
           comment-author: github-actions[bot]
+          body-includes: "perf-results"
+
       - id: post-report-as-pr-comment
         name: Post Report as Pull Request Comment
         uses: peter-evans/create-or-update-comment@v4
         with:
           issue-number: ${{ github.event.pull_request.number }}
-          body: "Performance Ratio:\nRatio of time to compute gradient and time to compute function.\nWarning: results are very approximate! See [here](https://github.com/chalk-lab/Mooncake.jl/tree/main/bench#inter-framework-benchmarking) for more context.\n```\n${{ steps.read-file.outputs.table }}\n```"
+          body: |
+            <!-- perf-results -->
+            Performance Ratio:
+            Ratio of time to compute gradient and time to compute function.
+            Warning: results are very approximate! See [here](https://github.com/chalk-lab/Mooncake.jl/tree/main/bench#inter-framework-benchmarking) for more context.
+            ```
+            ${{ steps.read-file.outputs.table }}
+            ```
           comment-id: ${{ steps.fc.outputs.comment-id }}
           edit-mode: replace

.github/workflows/documentation.yml

@@ -7,26 +7,18 @@ on:
     tags: '*'
   pull_request:
 
+permissions:
+  contents: write
+  pull-requests: write
+
 jobs:
-  build:
-    permissions:
-      contents: write
-      pull-requests: read
-      statuses: write
-      actions: write
+  docs:
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v4
-      - uses: julia-actions/setup-julia@v2
-        with:
-          version: '1'
-          arch: x64
-          include-all-prereleases: false
-      - name: Install dependencies
-        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.update(); Pkg.instantiate()'
-      - name: Build and deploy
+      - name: Build and deploy Documenter.jl docs
         env:
           GKSwstype: nul # turn off GR's interactive plotting for notebooks
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+        uses: TuringLang/actions/DocsDocumenter@main
+
+

docs/src/index.md

@@ -151,7 +151,4 @@ Please be aware that by "performant" we mean similar or better performance than
 
 ### What won't work
 
-While `Mooncake.jl` should now work on a very large subset of the language, there remain things that you should expect not to work. A non-exhaustive list of things to bear in mind includes:
-1. It is always necessary to produce hand-written rules for `ccall`s (and, more generally, foreigncall nodes). We have rules for many `ccall`s, but not all. If you encounter a foreigncall without a hand-written rule, you should get an informative error message which tells you what is going on and how to deal with it.
-1. Builtins which require rules. The vast majority of them have rules now, but some don't. You should get a sensible error if you encounter a primitive without a rule.
-1. Anything involving tasks / threading -- we have no thread safety guarantees and, at the time of writing, I'm not entirely sure what error you will find if you attempt to AD through code which uses Julia's task / thread system. The same applies to distributed computing. These limitations ought to be possible to resolve.
+See [known limitations](known_limitations.md). 

docs/src/known_limitations.md

@@ -2,6 +2,13 @@
 
 Mooncake.jl has a number of known qualitative limitations, which we document here.
 
+## Coverage of Julia Syntax and Standard Library
+
+While `Mooncake.jl` should now work on a very large subset of the language, there remain things that you should expect not to work. A non-exhaustive list of things to bear in mind includes:
+1. It is always necessary to produce hand-written rules for `ccall`s (and, more generally, foreigncall nodes). We have rules for many `ccall`s, but not all. If you encounter a foreigncall without a hand-written rule, you should get an informative error message which tells you what is going on and how to deal with it.
+1. Builtins which require rules. The vast majority of them have rules now, but some don't. You should get a sensible error if you encounter a primitive without a rule.
+1. Anything involving tasks / threading -- we have no thread safety guarantees and, at the time of writing, I'm not entirely sure what error you will find if you attempt to AD through code which uses Julia's task / thread system. The same applies to distributed computing. These limitations ought to be possible to resolve.
+
 ## Mutation of Global Variables
 
 ```@meta
@@ -154,3 +161,4 @@ Honestly, your best bet is just to avoid differentiating functions whose argumen
 ```@meta
 DocTestSetup = nothing
 ```
+