Merge 68d231c into d45889d

.github/workflows/pages.yml

@@ -0,0 +1,54 @@
+name: Build and Deploy mdBook
+
+on:
+  # automatically update docs when pushing to master
+  push:
+    branches: [ "master" ]
+  # also allow to run the workflow manually from the actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      - name: Build the book
+        run: |
+          cd docs
+          ./generate/build.sh "3.9.3"
+          cargo install mdbook mdbook-linkcheck mdbook-toc mdbook-alerts
+          mdbook build
+
+      - name: Upload
+        uses: actions/upload-pages-artifact@v3
+        with:
+          name: github-pages
+          path: ./docs/out/html
+
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.vscode/settings.json

@@ -17,5 +17,8 @@
     "Lua.workspace.library": [
         "types/nerdo"
     ],
+    "Lua.workspace.ignoreDir": [
+        "docs"
+    ],
     "Lua.hint.arrayIndex": "Disable"
 }

docs/.gitignore

@@ -0,0 +1,3 @@
+Cargo.lock
+/out/
+/target/

docs/.vscode/launch.json

@@ -0,0 +1,25 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "lldb",
+            "request": "launch",
+            "name": "Debug 'Generate API'",
+            "cargo": {
+                "args": [
+                    "build",
+                ],
+                "filter": {
+                    "kind": "bin"
+                }
+            },
+            "args": [
+                "${workspaceFolder}/../types/nerdo/library",
+                "${workspaceFolder}/src"
+            ],
+        },
+    ]
+}

docs/.vscode/tasks.json

@@ -0,0 +1,36 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "cargo",
+			"command": "run",
+			"problemMatcher": [
+				"$rustc"
+			],
+			"args": [
+				"${workspaceFolder}/../types/nerdo/library",
+				"${workspaceFolder}/src"
+			],
+			"group": "build",
+			"label": "build: API docs"
+		},
+		{
+			"type": "shell",
+			"command": "mdbook",
+			"args": [
+				"build"
+			],
+			"group": "build",
+			"label": "build: book",
+		},
+		{
+			"type": "shell",
+			"command": "mdbook",
+			"args": [
+				"serve"
+			],
+			"group": "build",
+			"label": "serve: book",
+		}
+	]
+}

docs/Cargo.toml

@@ -0,0 +1,5 @@
+[workspace]
+resolver = "2"
+members = [
+    "generate",
+]

docs/README.md

@@ -0,0 +1,21 @@
+## AFSEQ Book
+
+### Requirements
+
+The docs are generated using [mdBook](https://github.com/rust-lang/mdBook). To preview the pages locally you will need [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) to install mdbook, mdbook-linkcheck and mdbook-toc.
+
+```sh
+cargo install mdbook mdbook-linkcheck mdbook-toc
+```
+
+### Building
+
+Afterwards you can serve the docs at `localhost:3000` using mdbook, this will automatically refresh the browser tab whenever you change markdown files.
+
+```sh
+mdbook serve --open
+```
+
+### Generate API reference
+
+See [generate/README.md](./generate/README.md)

docs/book.toml

@@ -0,0 +1,22 @@
+[book]
+authors = ["[email protected]"]
+language = "en"
+multilingual = false
+src = "src"
+title = "AFSEQ"
+
+[build]
+build-dir = "out"
+create-missing = false
+
+[preprocessor.alerts]
+[preprocessor.toc]
+max-level = 3
+
+[output.html]
+default-theme = "dark"
+preferred-dark-theme = "ayu"
+additional-css = [ "src/styles.css" ]
+
+[output.linkcheck]
+warning-policy = "ignore"

docs/generate/.gitignore

@@ -0,0 +1 @@
+/lua-language-server/

docs/generate/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "generate"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+clap = { version = "4.5", features = ["derive"] }
+itertools = "0.13"
+pest = "2.7"
+pest_derive = "2.7"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+tempdir = "0.3"
+thiserror = "1.0"
+url = "2.5"

docs/generate/README.md

@@ -0,0 +1,45 @@
+# AFSEQ API Documentation Generator
+
+This is a rust app that generates the API definition chapters in the [AFSEQ book](https://emuell.github.io/afseq/) from the [Lua API definition](../../types/nerdo/) files.
+
+It is based on [matt-allan's](https://github.com/matt-allan) [mdbook-luacat](https://github.com/matt-allan/mdbook-luacats)  tool.
+
+
+## Building 
+
+### Requirements
+
+- [rust](https://www.rust-lang.org/tools/install) v1.56 or higher
+- [LuaLS](https://github.com/luals/lua-language-server) installation
+
+Note: The LuaLS installation must be placed into the folder [./lua-language-server](./lua-language-server) folder and **must be patched**. 
+
+See [build.sh](./build.sh) for details.
+
+### Building
+
+To create or update the API definitions chapter, build and run the app, then build the book:
+
+```bash
+# in the afseq root directory
+cd docs 
+# build and run the generate app to create the API definition
+cargo run -- ../../types/nerdo/ ./src 
+# serve or build the book
+mdbook serve 
+```
+
+---
+
+Alternatively, if you have vscode installed, open the XRNX repository folder and use the provided build task to build the API and the book:
+
+- `build: API Docs`: compiles and runs the API docs generator
+- `build: book`: compiles the mdbook
+- `serve: book`: serve and live update the book at //localhost:3000 
+
+
+## Debugging
+
+If you have vscode installed, open the XRNX root repository folder in vscode and use the `Debug: 'Generate API'` launch action.
+
+To debug and build the full API definition, change the launch arguments in the file [.vscode/launch.json](../.vscode/launch.json).

docs/generate/build.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -e
+
+LUA_LS_VERSION=$1
+
+pushd generate
+echo "downloading lua-language-server-${LUA_LS_VERSION}..."
+rm -rf lua-language-server && mkdir lua-language-server
+
+pushd lua-language-server
+rm -rf ./*
+wget -q -O - "https://github.com/LuaLS/lua-language-server/releases/download/${LUA_LS_VERSION}/lua-language-server-${LUA_LS_VERSION}-linux-x64.tar.gz" | tar xz
+
+echo "patching files..."
+sed -i.bak "s/\(\['Lua.hover.enumsLimit'\]\s*=\s*Type.Integer\s*>>\s*\)5\(,\)/\1100\2/" "script/config/template.lua"
+sed -i.bak -e "s/\(\['Lua.hover.expandAlias'\]\s*=\s*Type.Boolean\s*>>\s*\)true\(,\)/\1false\2/" "script/config/template.lua"
+sed -i.bak -e '/if \#view > 200 then/,/end/s/^/-- /' "script/vm/infer.lua"
+popd # lua-language-server
+
+echo "generating api docs..."
+cargo run -- "../../types/nerdo/library" "../src"

docs/generate/src/error.rs

@@ -0,0 +1,11 @@
+use std::io;
+
+#[derive(thiserror::Error, Debug)]
+pub enum Error {
+    #[error("IO error")]
+    Io(#[from] io::Error),
+    #[error("failed to execute lua-language-server")]
+    Exec,
+    #[error("unable to parse doc JSON")]
+    JsonParse(#[from] serde_json::Error),
+}