docs: Automatically generate documentation from goal_src code (#2214)

This automatically generates documentation from goal_src docstrings,
think doxygen/java-docs/rust docs/etc. It mostly supports everything
already, but here are the following things that aren't yet complete:
- file descriptions
- high-level documentation to go along with this (think pure markdown
docs describing overall systems that would be co-located in goal_src for
organizational purposes)
- enums
- states
- std-lib functions (all have empty strings right now for docs anyway)

The job of the new `gen-docs` function is solely to generate a bunch of
JSON data which should give you everything you need to generate some
decent documentation (outputting markdown/html/pdf/etc). It is not it's
responsibility to do that nice formatting -- this is by design to
intentionally delegate that responsibility elsewhere. Side-note, this is
about 12-15MB of minified json for jak 2 so far :)

In our normal "goal_src has changed" action -- we will generate this
data, and the website can download it -- use the information to generate
the documentation at build time -- and it will be included in the site.
Likewise, if we wanted to include docs along with releases for offline
viewing, we could do so in a similar fashion (just write a formatting
script to generate said documentation).

Lastly this work somewhat paves the way for doing more interesting
things in the LSP like:
- whats the docstring for this symbol?
- autocompleting function arguments
- type checking function arguments
- where is this symbol defined?
- etc

Fixes #2215

.github/workflows/inform-pages-repo.yaml

@@ -8,15 +8,75 @@ on:
       - 'goal_src/**'
 
 jobs:
-  inform:
-    name: Inform Pages Repo
+  gen-docs:
+    name: Generate Documentation
     if: github.repository == 'open-goal/jak-project'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
+    runs-on: ubuntu-20.04
+    timeout-minutes: 45
+    env: # overrides: https://github.com/mbitsnbites/buildcache/blob/master/doc/configuration.md
+      BUILDCACHE_MAX_CACHE_SIZE: 1000000000 # 1gb
+      BUILDCACHE_COMPRESS_FORMAT: ZSTD
+      BUILDCACHE_COMPRESS_LEVEL: 19
+      BUILDCACHE_DIRECT_MODE: true
+      BUILDCACHE_LOG_FILE: ${{ github.workspace }}/buildcache.log
     steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+
+      - name: Install Package Dependencies
+        run: >
+          sudo apt install build-essential cmake
+          clang gcc g++ lcov make nasm libxrandr-dev
+          libxinerama-dev libxcursor-dev libpulse-dev
+          libxi-dev zip ninja-build
+
+      - name: Setup Buildcache
+        uses: mikehardy/buildcache-action@v2.1.0
+        with:
+          cache_key: linux-ubuntu-20.04-${{ inputs.cachePrefix }}-${{ inputs.cmakePreset }}
+          buildcache_tag: v0.28.1
+
+      - name: CMake Generation
+        env:
+          CC: clang
+          CXX: clang++
+        run: |
+          cmake -B build --preset=${{ inputs.cmakePreset }} \
+            -DCMAKE_C_COMPILER_LAUNCHER=${{ github.workspace }}/buildcache/bin/buildcache \
+            -DCMAKE_CXX_COMPILER_LAUNCHER=${{ github.workspace }}/buildcache/bin/buildcache
+
+      - name: Build Project
+        run: cmake --build build --parallel $((`nproc`)) --target goalc
+
+      - name: Generate Docs For Jak 1
+        run: |
+          ./build/goalc/goalc --cmd "(begin (make-group \"all-code\") (gen-docs \"${PWD}\"))" --game jak1
+
+      - name: Generate Docs For Jak 2
+        run: |
+          ./build/goalc/goalc --cmd "(begin (make-group \"all-code\") (gen-docs \"${PWD}\"))" --game jak2
+
+      - name: Upload Docs Artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: opengoal-docs
+          if-no-files-found: error
+          path: |
+            ./jak1*.json
+            ./jak2*.json
+
+      - name: Get Artifact ID
+        env:
+          GITHUB_TOKEN: ${{ secrets.BOT_PAT }}
+        id: get-artifact-id
+        run: | # grab the id of the artifact we just created
+          echo "ARTIFACT_ID=$(gh api -H 'Accept: application/vnd.github+json' ${{github.event.workflow_run.artifacts_url}} --jq .artifacts[].id)" >> $GITHUB_ENV
+          echo "artifact id is ${{ env.ARTIFACT_ID }}"
+
       - name: Send Dispatch
         uses: peter-evans/repository-dispatch@v2
         with:
           token: ${{ secrets.BOT_PAT }}
           repository: 'open-goal/open-goal.github.io'
           event-type: updateProgress
+          client-payload: '{"docArtifactId": "${{ env.ARTIFACT_ID }}"}'