Clean up lua docs scripts

- ldoc is now a git submodule
- ldoc can be installed using scripts/install.{sh,ps1}
- lua docs can be build using scripts/build.{sh,ps1}
- all lua docs-related files now reside inside of the docs folder

.github/workflows/generate-lua-docs.yml

@@ -13,30 +13,22 @@ jobs:
     steps:
       - name: Checkout branch
         uses: actions/checkout@v2
-        
+        with:
+          submodules: recursive
+
       - uses: leafo/gh-actions-lua@v8.0.0
         with:
           luaVersion: "5.2"
 
       - uses: leafo/gh-actions-luarocks@v4.0.0
 
-      - name: Pull LDoc
-        uses: actions/checkout@v2
-        with:
-          repository: impulsh/LDoc
-          path: ldoc
+      - name: Run install script
+        working-directory: docs
+        run: ./scripts/install.sh
 
-      - name: Build LDoc
-        working-directory: ldoc
-        run: luarocks make
-
-      - name: Build docs
-        run: ldoc .
-
-      - name: Copy assets
-        run: |
-          cp -v docs/css/* docs/html
-          cp -v docs/js/* docs/html
+      - name: Run build script
+        working-directory: docs
+        run: ./scripts/build.sh
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

.gitignore

@@ -51,7 +51,6 @@ desktop.ini
 # Merge script
 temp.txt
 
-docs/html
 # Private assets
 Barotrauma/BarotraumaShared/Content/*
 Barotrauma/**/GameAnalyticsKeys.cs

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "Libraries/moonsharp"]
 	path = Libraries/moonsharp
 	url = https://github.com/evilfactory/moonsharp.git
+[submodule "docs/libs/ldoc"]
+	path = docs/libs/ldoc
+	url = https://github.com/impulsh/LDoc.git

docs/.gitignore

@@ -0,0 +1,2 @@
+html
+lua_modules

docs/build_docs.bat

@@ -1,5 +0,0 @@
-xcopy css html /Y
-xcopy js html /Y
-cd ..
-lua B:\programming\lua\LDoc\ldoc.lua .
-cd docs

docs/config.ld

@@ -1,24 +1,26 @@
+-- vim:ft=lua
 
 file = {
-	"docs/lua"
+  "lua"
 }
 
-module_file = {
+module_file = {}
 
-}
-
-dir = "docs/html"
+dir = "html"
 project = "LuaForBarotrauma"
 title = "LuaForBarotrauma Documentation"
 
 no_space_before_args = true
-style = "docs/css"
-template = "docs/templates"
+style = "css"
+template = "templates"
 format = "markdown"
 ignore = true
-topics = "docs/manual"
+topics = "manual"
 use_markdown_titles = true
-kind_names = {topic = "Manual", module = "Classes"}
+kind_names = {
+  topic = "Manual",
+  module = "Classes"
+}
 merge = true
 sort = true
 sort_modules = true
@@ -31,20 +33,20 @@ pretty_urls = true -- avoid showing .html in urls
 pretty_topic_names = true -- strips extension from manual filenames, this does not check filename collisions
 
 custom_tags = {
-	{"realm", hidden = true},
-	{"internal", hidden = true}
+  {"realm", hidden = true},
+  {"internal", hidden = true}
 }
 
 custom_display_name_handler = function(item, default_handler)
-	if (item.type == "function" and item.module) then
-		if (item.module.type == "classmod" or item.module.type == "panel") then
-			return item.module.mod_name .. ":" .. default_handler(item)
-		elseif (item.module.type == "hooks") then
-			return item.module.mod_name:upper() .. ":" .. default_handler(item)
-		end
-	end
+  if (item.type == "function" and item.module) then
+    if (item.module.type == "classmod" or item.module.type == "panel") then
+      return item.module.mod_name .. ":" .. default_handler(item)
+    elseif (item.module.type == "hooks") then
+      return item.module.mod_name:upper() .. ":" .. default_handler(item)
+    end
+  end
 
-	return default_handler(item)
+  return default_handler(item)
 end
 
 new_type("code", "Code", true)

docs/http_server.bat

@@ -1 +0,0 @@
-py -m http.server -d html

docs/scripts/build.ps1

@@ -0,0 +1,17 @@
+try {
+  cd $PSScriptRoot/..
+
+  Remove-Item -Force -Recurse ./html | Out-Null
+  New-Item -ItemType Directory ./html | Out-Null
+  Copy-Item -Path ./css/. -Destination ./html -Recurse -Force | Out-Null
+  Copy-Item -Path ./js/. -Destination ./html -Recurse -Force | Out-Null
+
+  if ((Get-Command "lua_modules/bin/ldoc" -ErrorAction SilentlyContinue) -eq $null) {
+    echo "ldoc not found; please run docs/scripts/install.ps1"
+    exit 1
+  }
+
+  lua_modules/bin/ldoc .
+} finally {
+  popd
+}

docs/scripts/build.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+cd "$DIR/.."
+
+ldoc_path=./lua_modules/bin/ldoc
+
+if [[ ! -x "$ldoc_path" ]]; then
+  echo "ldoc not found; please run docs/scripts/install.sh"
+  exit 1
+fi
+
+rm -rf ./html
+mkdir ./html
+
+cp -r ./js/. ./html
+cp -r ./css/. ./html
+
+"$ldoc_path" .

docs/scripts/install.ps1

@@ -0,0 +1,41 @@
+try {
+  cd $PSScriptRoot/..
+
+  $lua_binary = $env:LUA_BINARY
+  if ($lua_binary -eq $null) {
+    $lua_binary = "lua"
+  }
+
+  if ((Get-Command "$lua_binary" -ErrorAction SilentlyContinue) -eq $null) {
+    if ($env:LUA_BINARY -eq $null) {
+      echo "lua binary not found; please set `$LUA_BINARY manually."
+    } else {
+      echo "lua binary not found: $lua_binary"
+    }
+    exit 1
+  }
+
+  if ((Get-Command "luarocks" -ErrorAction SilentlyContinue) -eq $null) {
+    echo "luarocks not found"
+    exit 1
+  }
+
+  $lua_version = (Invoke-Expression -Command "& $lua_binary -v 2>&1") -Replace '^Lua (\d+)\.(\d+).*$','$1.$2'
+  echo "Detected lua version $lua_version"
+
+  $luarocks_args=@(
+    "--tree",
+    "$(Get-Location)/lua_modules",
+    "--lua-version",
+    "$lua_version"
+  )
+
+  try {
+    cd ./libs/ldoc
+    luarocks @luarocks_args make
+  } finally {
+    popd
+  }
+} finally {
+  popd
+}

docs/scripts/install.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+cd "$DIR/.."
+
+lua_binary="${LUA_BINARY:-lua}"
+
+if ! command -v "$lua_binary" &> /dev/null; then
+  if [[ -z "${LUA_BINARY+x}" ]]; then
+    echo "lua binary not found; please set \$LUA_BINARY manually."
+  else
+    echo "lua binary not found: $lua_binary"
+  fi
+  exit 1
+fi
+
+if ! command -v "$lua_binary" &> /dev/null; then
+  echo "luarocks not found"
+  exit 1
+fi
+
+lua_version="$("$lua_binary" -v | grep -Po '^Lua \K(\d+)\.(\d+)')"
+echo "Detected lua version $lua_version"
+
+# Install dependencies (npm style)
+# NOTE: you need to have lua header files installed.
+# On debian-based distros: apt install libluaX.X-dev
+
+luarocks_args=(
+  "--tree"
+  "$PWD/lua_modules"
+  "--lua-version"
+  "$lua_version"
+)
+
+(
+  cd libs/ldoc
+  luarocks ${luarocks_args[@]} make
+)

docs/scripts/serve.ps1

@@ -0,0 +1,12 @@
+try {
+  cd $PSScriptRoot/..
+
+  if ((Get-Command "python3" -ErrorAction SilentlyContinue) -eq $null) {
+    echo "python3 not found"
+    exit 1
+  }
+
+  python3 -m http.server -d html
+} finally {
+  popd
+}

docs/scripts/serve.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+cd "$DIR/.."
+
+if ! command -v "python3" &> /dev/null; then
+  echo "python3 not found"
+  exit 1
+fi
+
+python3 -m http.server -d html

docs/templates/ldoc.ltp

@@ -55,18 +55,18 @@ end
 
 	<body>
 		<main>
-			{(docs/templates/sidebar.ltp)}
+			{(templates/sidebar.ltp)}
 
 			<article>
 				{% if (ldoc.root) then -- we're rendering the landing page (index.html) %}
-					{(docs/templates/landing.ltp)}
+					{(templates/landing.ltp)}
 				{% elseif (ldoc.body) then -- we're rendering non-code elements %}
 					<div class="wrapper">
 						{* ldoc.body *}
 					</div>
 				{% elseif (module) then -- we're rendering libary contents %}
 					<div class="wrapper">
-						{(docs/templates/module.ltp)}
+						{(templates/module.ltp)}
 					</div>
 				{% end %}
 			</article>