Convert LDoc to lua-language-server (#1775)

* Automatic update from ldoc -> lls syntax Using a set of simple regexp replacements to convert from LDoc compatible lua doc syntax. Script used: https://github.com/rhys-vdw/spring-lua-doc-converter * LuaBitOps.cpp: Update Lua docs * LuaConstCOB.cpp: Update Lua docs * LuaConstCMD.cpp: Update Lua docs * LuaConstCMDTYPE.cpp: Update Lua docs * LuaConstGL.cpp: Update Lua docs * LuaConstGame.cpp: Update Lua docs * LuaConstPlatform.cpp: Update Lua docs * LuaConstGL.cpp: Define GLenum in Lua * LuaFBOs.cpp: Update Lua docs * LuaHandle.cpp: Update Lua docs * LuaHandleSynced.cpp: Update Lua docs * Lua docs: cmdOpts -> CommandOptions * Lua docs: mods -> KeyModifiers * LuaMathExtra.cpp: Update Lua docs * LuaMenu.cpp: Update Lua docs * LuaMetalMap.cpp: Update Lua docs * LuaOpenGL.cpp: Update Lua docs * LuaRBOs.cpp: Update Lua docs * LuaShaders.cpp: Update Lua docs * LuaSyncedCtrl.cpp: Update Lua docs * LuaVBO.cpp: Update Lua docs * Create Types.lua To contain type definitions shared between the various cpp lua files * LuaUnsyncedRead.cpp: Update Lua docs And move some more definitions into `Types.lua` * LuaVAO.cpp, LuaVAOImpl.cpp: Update Lua docs * LuaVBO.cpp, LuaVBOImpl.cpp: Update Lua docs * LuaIntro.cpp: Update Lua docs * Fix typo * Lua: GLenum -> GL * Better Lua types * Move resource types into Types.lua * Add .luarc.json * Create Lua regeneration script To be replace with github action * Regenerate Lua library * Add GitHub workflow to regenerate Lua metafiles * Remove Lua script * FIX .luarc.json * Lua library action updates submodule * Set git config globally * Update lua-api.md Written by badosu * Add guide for generating LuaLS docs * Update site README with specific Ruby version * Remove params from generated Lua API methods * Update Gemfile * Use correct LLS doc filename * WIP Messing with .luarc.json * Add ignores to luarc * lua-api.md improvements Fixing a bunch of bad stuff. * Add syntax highlighting on doc "view" * Update docs README Change the command to generate from root, because of a bug where using relative paths causes duplicated generation. * Show the definition for alias types * Remove double hr in API docs * Add guide for installing lua-doc-extractor * Remove use of external Lua library repo * Add LUA_DOC_GUIDE * Generate docs using Lua Language Server * Update LuaTracyExtra.cpp * Update LuaTableExtra * Update LuaLS library * Allow publishing site from other branches For testing * Remove LDoc config * Revert "Remove use of external Lua library repo" This reverts commit 81874c2. * Remove disabled libs from main luarc * Do not push generated lua library to Recoil repo * Delete generated Lua library * Update LuaFonts LDoc -> LLS * LDoc -> LLS * More LDoc -> LLS cleanup * Fix some stuff after rebase * Add recoil-lua-library submodule * Keep the local lua library updated * Add Facing alias * Init submodule before updating * Update Lua libary submodule * Update Lua doc guide * Move Lua guide into site guides * Update site readme for lua language server * Init library submodule before generating API docs * Prefer SSH key lua library deployment * Update Lua libary submodule * Point workflow to beyond-all-reason/recoil-lua-library * Update submodule to beyond-all-reason/recoil-lua-library * Update doc link to beyond-all-reason/recoil-lua-library * Remove LDoc from gitignore * Install lua-doc-extractor from npm * Add comment to .luarc.doc.json * Ignore lua-language-server doc export * Add header to lua-language-server guide * Add section on IDE support for Lua * Fix manual Lua doc export steps * Ignore .bundle in site folder Contains local bundle config * Add note about bad docs to Lua API page * Install lua-doc-extractor globally * Remove recoil-lua-library submodule * Do not add .luarc.json to library repo * Fix typo in lua-language-server doc gen command * Remove doc/site/ldoc folder * Prefer rgb type * Clean up lua doc for SetHeightMap * lua-api.markdown: Show ... varargs param properly * Remove TOC from lua-api.md * Fix ActiveCommandChanged params * Add source link to recoil-lua-library * Open source links in new tab * Remove type from API heading * Remove meta comment from losAccess doc * Fix workflow link * Fix library path * Add author to lls guide * Add changelog entry * Remove required arguments from `math.bit_*` * Revert "Add changelog entry" This reverts commit f79ebc3. * Fix up some docs in LuaUnsyncedCtrl.cpp * Prefer integer type for ID params * Add more detailed lua language support changelog * Remove engine dev notes from changelog * Split LLS docs into two engine and game dev articles --------- Co-authored-by: rhys-vdw <[email protected]> Co-authored-by: rhys-vdw <[email protected]>
beyond-all-reason · Feb 5, 2025 · db84f0f · db84f0f
1 parent 5e61b73
commit db84f0f
Show file tree

Hide file tree

Showing 51 changed files with 5,413 additions and 4,995 deletions.
diff --git a/.github/workflows/generate-lua-library.yml b/.github/workflows/generate-lua-library.yml
@@ -0,0 +1,55 @@
+name: Generate Lua library
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+    paths:
+      - 'rts/Lua/**'
+jobs:
+  generate-library:
+    name: Regenerate library
+    runs-on: ubuntu-latest
+    steps:
+      - name: Configure git
+        run: |
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+
+      - name: Checkout Lua CPP files
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: rts/Lua
+          path: recoil
+
+      # NOTE: This step is duplicated in `publish-site.yml`
+      - name: Generate Lua library
+        working-directory: recoil/rts/Lua/
+        run: |
+          npm install -g lua-doc-extractor
+          lua-doc-extractor *.cpp --dest library/generated
+
+      - name: Check out library repo
+        uses: actions/checkout@v4
+        with:
+          repository: beyond-all-reason/recoil-lua-library
+          ssh-key: ${{ secrets.RECOIL_LUA_LIBRARY_SSH_KEY }}
+          path: library
+
+      - name: Copy changes into library repo
+        run: |
+          rm -rf library/library
+          cp -r recoil/rts/Lua/library library
+          # Remove .luarc.json (this is only required for doc gen)
+          rm library/library/.luarc.json
+
+      # Always try to update library repo (even if generation did not make changes).
+      # Hand-written files may have changed without generated output changing,
+      # and library may simply be out of date for whatever reason.
+      - name: Commit and push library repo
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          repository: ./library
+          commit_message: |
+            Update library
+            Generated from https://github.com/${{ github.repository }}/commit/${{ github.sha }}
diff --git a/.github/workflows/publish-site.yml b/.github/workflows/publish-site.yml
@@ -13,22 +13,37 @@ jobs:
       - name: Install Dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install --fix-missing -y lua-ldoc lua-markdown jq p7zip-full libsdl2-2.0-0 libopenal1
+          sudo apt-get install --fix-missing -y jq p7zip-full libsdl2-2.0-0 libopenal1
+      - name: Set up Homebrew
+        id: set-up-homebrew
+        uses: Homebrew/actions/setup-homebrew@master
+      - name: Install Lua Language Server
+        run: |
+          brew install lua-language-server
       - name: Checkout Source Repository
         uses: actions/checkout@v2
-        with:
-          ref: master
       - name: Generate Dynamic Content
         run: |
           bash doc/site/_scripts/get_release_data.sh
           bash doc/site/_scripts/get_engine_data.sh
           git add -f doc/site/_data
-      - name: Run LDoc
+      # NOTE: This step is duplicated in `generate-lua-library.yml`
+      - name: Generate Lua library
+        working-directory: rts/Lua/
+        run: |
+          npm install -g lua-doc-extractor
+          lua-doc-extractor *.cpp --dest library/generated
+      # NOTE: Running LLS 3.13.4 from a subdirectory with a relative path seems
+      # to cause duplicate class fields to be generated. Presumably a bug in
+      # LLS.
+      - name: Export Lua data using Lua Language Server
+        run: |
+          lua-language-server --doc rts/Lua/library --doc_out_path doc/site/_data
+          git add -f doc/site/_data
+      - name: Commit changes
         run: |
-          ldoc -c doc/LDoc/config.ld .
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git config user.name "github-actions[bot]"
-          git add -f doc/site/ldoc
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
           git commit -m "Update doc/site"
       - name: Check if gh-pages exists
         id: check-ghpages
@@ -39,8 +54,8 @@ jobs:
         id: site-changes
         if: steps.check-ghpages.outputs.exists == 'true'
         run: |
-          git diff --stat origin/gh-pages master:doc/site
-          git diff --quiet origin/gh-pages master:doc/site && (echo "modified=false" > $GITHUB_OUTPUT) || (echo "modified=true" > $GITHUB_OUTPUT)
+          git diff --stat origin/gh-pages ${{ github.ref_name }}:doc/site
+          git diff --quiet origin/gh-pages ${{ github.ref_name }}:doc/site && (echo "modified=false" > $GITHUB_OUTPUT) || (echo "modified=true" > $GITHUB_OUTPUT)
       - name: Push gh-pages # Only push gh-pages if doc/site/ was changed or ldoc did changes
         if: steps.check-ghpages.outputs.exists == 'false' || steps.site-changes.outputs.modified == 'true'
         run: |

diff --git a/.gitignore b/.gitignore
@@ -153,19 +153,23 @@ x64/
 *.sln
 *.db
 Spring.VC.VC.opendb
-/out/build/** 
+/out/build/**
 
 # downloaded files
 /pool
 /maps
 /rapid
 /packages
 
-# ignore autogenerated doc
-/doc/site/ldoc
-
 # ignore local development paths
 .cache
 toolchain
 compile_commands.json
 build-*
+
+# Lua Language Server doc output
+/doc/site/_data/doc.json
+/doc/site/_data/doc.md
+
+# lua-doc-extractor generated library
+/rts/Lua/library/generated
diff --git a/doc/LDoc/README.md b/doc/LDoc/README.md
diff --git a/doc/LDoc/config.ld b/doc/LDoc/config.ld