diff --git a/.github/workflows/generate-lua-docs.yml b/.github/workflows/generate-lua-docs.yml index 42b930917..365c823f7 100644 --- a/.github/workflows/generate-lua-docs.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 83b4a80fa..7d4b67772 100644 --- a/.gitignore +++ b/.gitignore @@ -51,7 +51,6 @@ desktop.ini # Merge script temp.txt -docs/html # Private assets Barotrauma/BarotraumaShared/Content/* Barotrauma/**/GameAnalyticsKeys.cs diff --git a/.gitmodules b/.gitmodules index dd5e75d54..399c0ff11 100644 --- a/.gitmodules +++ b/.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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..97249b860 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +html +lua_modules diff --git a/docs/build_docs.bat b/docs/build_docs.bat deleted file mode 100644 index 2cc1e0904..000000000 --- a/docs/build_docs.bat +++ /dev/null @@ -1,5 +0,0 @@ -xcopy css html /Y -xcopy js html /Y -cd .. -lua B:\programming\lua\LDoc\ldoc.lua . -cd docs \ No newline at end of file diff --git a/config.ld b/docs/config.ld similarity index 74% rename from config.ld rename to docs/config.ld index 79cc5cf19..b0b9ed32d 100644 --- a/config.ld +++ b/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) diff --git a/docs/http_server.bat b/docs/http_server.bat deleted file mode 100644 index e57abb414..000000000 --- a/docs/http_server.bat +++ /dev/null @@ -1 +0,0 @@ -py -m http.server -d html \ No newline at end of file diff --git a/docs/libs/ldoc b/docs/libs/ldoc new file mode 160000 index 000000000..69ef8c976 --- /dev/null +++ b/docs/libs/ldoc @@ -0,0 +1 @@ +Subproject commit 69ef8c976e3ac94146f87e99c8885211128a1c13 diff --git a/docs/scripts/build.ps1 b/docs/scripts/build.ps1 new file mode 100644 index 000000000..850f8f7a3 --- /dev/null +++ b/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 +} diff --git a/docs/scripts/build.sh b/docs/scripts/build.sh new file mode 100755 index 000000000..df79e31cd --- /dev/null +++ b/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" . diff --git a/docs/scripts/install.ps1 b/docs/scripts/install.ps1 new file mode 100644 index 000000000..262e7f93c --- /dev/null +++ b/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 +} diff --git a/docs/scripts/install.sh b/docs/scripts/install.sh new file mode 100755 index 000000000..a1b868bb5 --- /dev/null +++ b/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 +) diff --git a/docs/scripts/serve.ps1 b/docs/scripts/serve.ps1 new file mode 100644 index 000000000..9a9bffed2 --- /dev/null +++ b/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 +} diff --git a/docs/scripts/serve.sh b/docs/scripts/serve.sh new file mode 100755 index 000000000..198bca784 --- /dev/null +++ b/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 diff --git a/docs/templates/ldoc.ltp b/docs/templates/ldoc.ltp index d0b6f6e6f..95ad3f592 100644 --- a/docs/templates/ldoc.ltp +++ b/docs/templates/ldoc.ltp @@ -55,18 +55,18 @@ end
- {(docs/templates/sidebar.ltp)} + {(templates/sidebar.ltp)}
{% 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 %}
{* ldoc.body *}
{% elseif (module) then -- we're rendering libary contents %}
- {(docs/templates/module.ltp)} + {(templates/module.ltp)}
{% end %}