From de7224ff7263ce0206e300398c1ca18f38f98b04 Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 23 Sep 2024 16:19:50 +0300 Subject: [PATCH 01/12] Install and configure typedoc --- .gitignore | 1 + package-lock.json | 650 +++++++++++++++++++++++++++++++++- packages/langium/package.json | 4 +- packages/langium/typedoc.json | 13 + 4 files changed, 666 insertions(+), 2 deletions(-) create mode 100644 packages/langium/typedoc.json diff --git a/.gitignore b/.gitignore index f1596575a..4766d1eff 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ .vscode-test/ coverage/ dist/ +docs/ lib/ out/ node_modules/ diff --git a/package-lock.json b/package-lock.json index 53afd5b84..c8c0c65dd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1540,6 +1540,62 @@ "win32" ] }, + "node_modules/@shikijs/core": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.17.7.tgz", + "integrity": "sha512-ZnIDxFu/yvje3Q8owSHaEHd+bu/jdWhHAaJ17ggjXofHx5rc4bhpCSW+OjC6smUBi5s5dd023jWtZ1gzMu/yrw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/engine-javascript": "1.17.7", + "@shikijs/engine-oniguruma": "1.17.7", + "@shikijs/types": "1.17.7", + "@shikijs/vscode-textmate": "^9.2.2", + "@types/hast": "^3.0.4", + "hast-util-to-html": "^9.0.2" + } + }, + "node_modules/@shikijs/engine-javascript": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-1.17.7.tgz", + "integrity": "sha512-wwSf7lKPsm+hiYQdX+1WfOXujtnUG6fnN4rCmExxa4vo+OTmvZ9B1eKauilvol/LHUPrQgW12G3gzem7pY5ckw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "1.17.7", + "@shikijs/vscode-textmate": "^9.2.2", + "oniguruma-to-js": "0.4.3" + } + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-1.17.7.tgz", + "integrity": "sha512-pvSYGnVeEIconU28NEzBXqSQC/GILbuNbAHwMoSfdTBrobKAsV1vq2K4cAgiaW1TJceLV9QMGGh18hi7cCzbVQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "1.17.7", + "@shikijs/vscode-textmate": "^9.2.2" + } + }, + "node_modules/@shikijs/types": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-1.17.7.tgz", + "integrity": "sha512-+qA4UyhWLH2q4EFd+0z4K7GpERDU+c+CN2XYD3sC+zjvAr5iuwD1nToXZMt1YODshjkEGEDV86G7j66bKjqDdg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^9.2.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "9.2.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-9.2.2.tgz", + "integrity": "sha512-TMp15K+GGYrWlZM8+Lnj9EaHEFmOen0WJBrfa17hF7taDOYthuPPV0GWzfd/9iMij0akS/8Yw2ikquH7uVi/fg==", + "dev": true, + "license": "MIT" + }, "node_modules/@sigstore/protobuf-specs": { "version": "0.2.1", "resolved": "https://registry.npmjs.org/@sigstore/protobuf-specs/-/protobuf-specs-0.2.1.tgz", @@ -1642,6 +1698,16 @@ "@types/node": "*" } }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, "node_modules/@types/http-cache-semantics": { "version": "4.0.3", "resolved": "https://registry.npmjs.org/@types/http-cache-semantics/-/http-cache-semantics-4.0.3.tgz", @@ -1699,6 +1765,16 @@ "@types/lodash": "*" } }, + "node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, "node_modules/@types/minimatch": { "version": "3.0.5", "resolved": "https://registry.npmjs.org/@types/minimatch/-/minimatch-3.0.5.tgz", @@ -1737,6 +1813,13 @@ "@types/node": "*" } }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/vinyl": { "version": "2.0.9", "resolved": "https://registry.npmjs.org/@types/vinyl/-/vinyl-2.0.9.tgz", @@ -3228,6 +3311,17 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/ccount": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/chai": { "version": "4.4.1", "resolved": "https://registry.npmjs.org/chai/-/chai-4.4.1.tgz", @@ -3270,6 +3364,28 @@ "node": ">=10" } }, + "node_modules/character-entities-html4": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/chardet": { "version": "0.7.0", "resolved": "https://registry.npmjs.org/chardet/-/chardet-0.7.0.tgz", @@ -3489,6 +3605,17 @@ "node": ">=0.1.90" } }, + "node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/commander": { "version": "11.0.0", "resolved": "https://registry.npmjs.org/commander/-/commander-11.0.0.tgz", @@ -3978,12 +4105,36 @@ "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz", "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ==" }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, "node_modules/detect-node": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz", "integrity": "sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==", "dev": true }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "dev": true, + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/diff": { "version": "5.1.0", "resolved": "https://registry.npmjs.org/diff/-/diff-5.1.0.tgz", @@ -4163,6 +4314,19 @@ "once": "^1.4.0" } }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/err-code": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/err-code/-/err-code-2.0.3.tgz", @@ -6363,6 +6527,44 @@ "node": ">= 0.4" } }, + "node_modules/hast-util-to-html": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.3.tgz", + "integrity": "sha512-M17uBDzMJ9RPCqLMO92gNNUDuBSq10a25SDBI08iCCxmorf4Yy6sYHK57n9WAbRAAaU+DuR4W6GN9K4DFZesYg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^3.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "property-information": "^6.0.0", + "space-separated-tokens": "^2.0.0", + "stringify-entities": "^4.0.0", + "zwitch": "^2.0.4" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/hosted-git-info": { "version": "7.0.1", "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-7.0.1.tgz", @@ -6388,6 +6590,17 @@ "integrity": "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==", "dev": true }, + "node_modules/html-void-elements": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz", + "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/http-cache-semantics": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.1.1.tgz", @@ -7136,6 +7349,16 @@ "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", "dev": true }, + "node_modules/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "uc.micro": "^2.0.0" + } + }, "node_modules/load-json-file": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/load-json-file/-/load-json-file-4.0.0.tgz", @@ -7304,6 +7527,13 @@ "node": ">=10" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true, + "license": "MIT" + }, "node_modules/magic-string": { "version": "0.30.5", "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.5.tgz", @@ -7363,6 +7593,24 @@ "node": ">=4" } }, + "node_modules/markdown-it": { + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1", + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" + }, + "bin": { + "markdown-it": "bin/markdown-it.mjs" + } + }, "node_modules/matcher": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/matcher/-/matcher-3.0.0.tgz", @@ -7375,6 +7623,35 @@ "node": ">=10" } }, + "node_modules/mdast-util-to-hast": { + "version": "13.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.0.tgz", + "integrity": "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@ungap/structured-clone": "^1.0.0", + "devlop": "^1.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "trim-lines": "^3.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", + "dev": true, + "license": "MIT" + }, "node_modules/mem": { "version": "5.1.1", "resolved": "https://registry.npmjs.org/mem/-/mem-5.1.1.tgz", @@ -7637,6 +7914,100 @@ "node": ">= 8" } }, + "node_modules/micromark-util-character": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.0.tgz", + "integrity": "sha512-KvOVV+X1yLBfs9dCBSopq/+G1PcgT3lAK07mC4BzXi5E7ahzMAF8oIupDDJ6mievI6F+lAATkbQQlQixJfT3aQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.0.tgz", + "integrity": "sha512-pS+ROfCXAGLWCOc8egcBvT0kf27GoWMqtdarNfDcjb6YLuV5cM3ioG45Ys2qOVqeqSbjaKg72vU+Wby3eddPsA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.0.tgz", + "integrity": "sha512-WhYv5UEcZrbAtlsnPuChHUAsu/iBPOVaEVsntLBIdpibO0ddy8OzavZz3iL2xVvBZOpolujSliP65Kq0/7KIYw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.0.tgz", + "integrity": "sha512-8JZt9ElZ5kyTnO94muPxIGS8oyElRJaiJO8EzV6ZSyGQ1Is8xwl4Q45qU5UOg+bGH4AikWziz0iN4sFLWs8PGw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.0.tgz", + "integrity": "sha512-oNh6S2WMHWRZrmutsRmDDfkzKtxF+bc2VxLC9dvtrDIRFln627VsFP6fLMgTryGDljgLPjkrzQSDcPrjPyDJ5w==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, "node_modules/micromatch": { "version": "4.0.5", "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", @@ -8286,6 +8657,19 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/oniguruma-to-js": { + "version": "0.4.3", + "resolved": "https://registry.npmjs.org/oniguruma-to-js/-/oniguruma-to-js-0.4.3.tgz", + "integrity": "sha512-X0jWUcAlxORhOqqBREgPMgnshB7ZGYszBNspP+tS9hPD3l13CdaXcHbgImoHUHlrvGx/7AvFEkTRhAGYh+jzjQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "regex": "^4.3.2" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, "node_modules/open": { "version": "8.4.2", "resolved": "https://registry.npmjs.org/open/-/open-8.4.2.tgz", @@ -9111,6 +9495,17 @@ "node": ">=10" } }, + "node_modules/property-information": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-6.5.0.tgz", + "integrity": "sha512-PgTgs/BlvHxOu8QuEN7wi5A0OmXaBcHpmCSTehcs6Uuu9IkDIEo13Hy7n898RHfrQ49vKCoGeWZSaAK01nwVig==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/proto-list": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/proto-list/-/proto-list-1.2.4.tgz", @@ -9135,6 +9530,16 @@ "node": ">=6" } }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, "node_modules/pupa": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/pupa/-/pupa-2.1.1.tgz", @@ -9426,6 +9831,13 @@ "integrity": "sha512-kY1AZVr2Ra+t+piVaJ4gxaFaReZVH40AKNo7UCX6W+dEwBo/2oZJzqfuN1qLq1oL45o56cPaTXELwrTh8Fpggg==", "dev": true }, + "node_modules/regex": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/regex/-/regex-4.3.2.tgz", + "integrity": "sha512-kK/AA3A9K6q2js89+VMymcboLOlF5lZRCYJv3gzszXFHBr6kO6qLGzbm+UIugBEV8SMMKCTR59txoY6ctRHYVw==", + "dev": true, + "license": "MIT" + }, "node_modules/registry-auth-token": { "version": "5.0.2", "resolved": "https://registry.npmjs.org/registry-auth-token/-/registry-auth-token-5.0.2.tgz", @@ -9852,6 +10264,21 @@ "node": ">=4" } }, + "node_modules/shiki": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.17.7.tgz", + "integrity": "sha512-Zf6hNtWhFyF4XP5OOsXkBTEx9JFPiN0TQx4wSe+Vqeuczewgk2vT4IZhF4gka55uelm052BD5BaHavNqUNZd+A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "1.17.7", + "@shikijs/engine-javascript": "1.17.7", + "@shikijs/engine-oniguruma": "1.17.7", + "@shikijs/types": "1.17.7", + "@shikijs/vscode-textmate": "^9.2.2", + "@types/hast": "^3.0.4" + } + }, "node_modules/shx": { "version": "0.3.4", "resolved": "https://registry.npmjs.org/shx/-/shx-0.3.4.tgz", @@ -9995,6 +10422,17 @@ "node": ">=0.10.0" } }, + "node_modules/space-separated-tokens": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/spawn-command": { "version": "0.0.2", "resolved": "https://registry.npmjs.org/spawn-command/-/spawn-command-0.0.2.tgz", @@ -10187,6 +10625,21 @@ "node": ">=8" } }, + "node_modules/stringify-entities": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "dev": true, + "license": "MIT", + "dependencies": { + "character-entities-html4": "^2.0.0", + "character-entities-legacy": "^3.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/strip-ansi": { "version": "6.0.1", "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", @@ -10861,6 +11314,17 @@ "tree-kill": "cli.js" } }, + "node_modules/trim-lines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/trim-newlines": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/trim-newlines/-/trim-newlines-2.0.0.tgz", @@ -10974,6 +11438,55 @@ "is-typedarray": "^1.0.0" } }, + "node_modules/typedoc": { + "version": "0.26.7", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.7.tgz", + "integrity": "sha512-gUeI/Wk99vjXXMi8kanwzyhmeFEGv1LTdTQsiyIsmSYsBebvFxhbcyAx7Zjo4cMbpLGxM4Uz3jVIjksu/I2v6Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "lunr": "^2.3.9", + "markdown-it": "^14.1.0", + "minimatch": "^9.0.5", + "shiki": "^1.16.2", + "yaml": "^2.5.1" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x" + } + }, + "node_modules/typedoc/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/typedoc/node_modules/minimatch": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/typescript": { "version": "5.4.5", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz", @@ -10988,6 +11501,13 @@ "node": ">=14.17" } }, + "node_modules/uc.micro": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dev": true, + "license": "MIT" + }, "node_modules/ufo": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.3.2.tgz", @@ -11023,6 +11543,79 @@ "node": ">=8" } }, + "node_modules/unist-util-is": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.0.tgz", + "integrity": "sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz", + "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.0.0.tgz", + "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.1.tgz", + "integrity": "sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/universal-user-agent": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz", @@ -11379,6 +11972,36 @@ "spdx-expression-parse": "^3.0.0" } }, + "node_modules/vfile": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.2.tgz", + "integrity": "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/vinyl": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/vinyl/-/vinyl-3.0.0.tgz", @@ -12337,6 +12960,19 @@ "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz", "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==" }, + "node_modules/yaml": { + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.5.1.tgz", + "integrity": "sha512-bLQOjaX/ADgQ20isPJRvF0iRUHIxVhYvr53Of7wGcWlO2jvtUlH5m87DsmulFVxRpNLOnI4tB6p/oh8D7kpn9Q==", + "dev": true, + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/yargs-parser": { "version": "10.1.0", "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-10.1.0.tgz", @@ -13274,6 +13910,17 @@ "node": ">=0.10.0" } }, + "node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "packages/generator-langium": { "version": "3.2.0", "license": "MIT", @@ -13981,7 +14628,8 @@ "vscode-uri": "~3.0.8" }, "devDependencies": { - "langium-cli": "~3.2.0" + "langium-cli": "~3.2.0", + "typedoc": "^0.26.7" }, "engines": { "node": ">=16.0.0" diff --git a/packages/langium/package.json b/packages/langium/package.json index 753fb9153..24a9650bc 100644 --- a/packages/langium/package.json +++ b/packages/langium/package.json @@ -57,6 +57,7 @@ "build": "tsc", "watch": "tsc --watch", "lint": "eslint src test --ext .ts", + "docs": "typedoc", "validate-exports": "tsc -p test/tsconfig.export-main.json", "langium:generate": "langium generate", "langium:generate:production": "langium generate --mode=production", @@ -71,7 +72,8 @@ "vscode-uri": "~3.0.8" }, "devDependencies": { - "langium-cli": "~3.2.0" + "langium-cli": "~3.2.0", + "typedoc": "^0.26.7" }, "volta": { "node": "18.19.1", diff --git a/packages/langium/typedoc.json b/packages/langium/typedoc.json new file mode 100644 index 000000000..616192a71 --- /dev/null +++ b/packages/langium/typedoc.json @@ -0,0 +1,13 @@ +{ + "entryPoints": [ + "./src/index.ts", + "./src/generate/index.ts", + "./src/grammar/index.ts", + "./src/lsp/index.ts", + "./src/node/index.ts", + "./src/test/index.ts" + ], + "out": "./docs", + "includeVersion": true, + "githubPages": true +} From 5cd2c75732ffe828a0b3bfda9b8d5b5216f1fcd6 Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 23 Sep 2024 16:21:17 +0300 Subject: [PATCH 02/12] Fix some invalid JSDoc tags --- packages/langium/src/parser/async-parser.ts | 8 ++++---- packages/langium/src/serializer/json-serializer.ts | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/langium/src/parser/async-parser.ts b/packages/langium/src/parser/async-parser.ts index 494b41fbc..445a0c681 100644 --- a/packages/langium/src/parser/async-parser.ts +++ b/packages/langium/src/parser/async-parser.ts @@ -16,8 +16,8 @@ import { Emitter } from '../utils/event.js'; /** * Async parser that allows cancellation of the current parsing process. * - * @remark The sync parser implementation is blocking the event loop, which can become quite problematic for large files. - * @remark The default implementation is not actually async. It just wraps the sync parser in a promise. A real implementation would create worker threads or web workers to offload the parsing work. + * The sync parser implementation is blocking the event loop, which can become quite problematic for large files. + * The default implementation is not actually async. It just wraps the sync parser in a promise. A real implementation would create worker threads or web workers to offload the parsing work. */ export interface AsyncParser { /** @@ -27,7 +27,7 @@ export interface AsyncParser { * @param cancelToken A cancellation token that can be used to cancel the parsing process. * @returns A promise that resolves to the parse result. * - * @throw `OperationCancelled` if the parsing process is cancelled. + * @throws `OperationCancelled` if the parsing process is cancelled. */ parse(text: string, cancelToken: CancellationToken): Promise>; } @@ -35,7 +35,7 @@ export interface AsyncParser { /** * Default implementation of the async parser which simply wraps the sync parser in a promise. * - * @remark A real implementation would create worker threads or web workers to offload the parsing work. + * A real implementation would create worker threads or web workers to offload the parsing work. */ export class DefaultAsyncParser implements AsyncParser { diff --git a/packages/langium/src/serializer/json-serializer.ts b/packages/langium/src/serializer/json-serializer.ts index 4a92b4742..e21968776 100644 --- a/packages/langium/src/serializer/json-serializer.ts +++ b/packages/langium/src/serializer/json-serializer.ts @@ -57,7 +57,7 @@ export function isAstNodeWithComment(node: AstNode): node is AstNodeWithComment } /** - * A {@DocumentSegment} representing the definition area of an AstNode within the DSL text. + * A {@link DocumentSegment} representing the definition area of an AstNode within the DSL text. * Usually contains text region information on all assigned property values of the AstNode, * and may contain the defining file's URI as string. */ @@ -81,7 +81,7 @@ export interface JsonSerializer { /** * Serialize an `AstNode` into a JSON `string`. * @param node The `AstNode` to be serialized. - * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read. + * @param options Serialization options */ serialize(node: AstNode, options?: JsonSerializeOptions): string; /** From c684a74a79a07c8d97163c08c01fe752592a2f30 Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 23 Sep 2024 16:22:07 +0300 Subject: [PATCH 03/12] Fix JSDoc to correspond to function signatures --- packages/langium/src/generate/node-joiner.ts | 8 -------- packages/langium/src/references/linker.ts | 6 ++---- 2 files changed, 2 insertions(+), 12 deletions(-) diff --git a/packages/langium/src/generate/node-joiner.ts b/packages/langium/src/generate/node-joiner.ts index fad8a5bb8..473bfb29f 100644 --- a/packages/langium/src/generate/node-joiner.ts +++ b/packages/langium/src/generate/node-joiner.ts @@ -145,10 +145,6 @@ export function joinToNode( * @param property the value property name (string) corresponding to the appended content, * if e.g. the content corresponds to some `string` or `number` property of `astNode`, is optional * - * @param index the index of the value within a list property corresponding to the appended content, - * if the property contains a list of elements, is ignored otherwise, is optinal, - * should not be given if no `property` is given - * * @returns a function behaving as described above, which in turn returns a {@link CompositeGeneratorNode}. * * @example @@ -253,10 +249,6 @@ export function joinTracedToNode(source: T | undefined | Sour * @param property the value property name (string) corresponding to the appended content, * if e.g. the content corresponds to some `string` or `number` property of `astNode`, is optional * - * @param index the index of the value within a list property corresponding to the appended content, - * if the property contains a list of elements, is ignored otherwise, is optinal, - * should not be given if no `property` is given - * * @returns a function behaving as described above, which in turn returns a {@link CompositeGeneratorNode} or `undefined`. * * @example diff --git a/packages/langium/src/references/linker.ts b/packages/langium/src/references/linker.ts index d5cb303a5..2d3ccfb0e 100644 --- a/packages/langium/src/references/linker.ts +++ b/packages/langium/src/references/linker.ts @@ -42,9 +42,7 @@ export interface Linker { /** * Determines a candidate AST node description for linking the given reference. * - * @param node The AST node containing the reference. - * @param refId The reference identifier used to build a scope. - * @param reference The actual reference to resolve. + * @param refInfo Information about the reference. */ getCandidate(refInfo: ReferenceInfo): AstNodeDescription | LinkingError; @@ -60,8 +58,8 @@ export interface Linker { * and further resolution attempts will *not* be performed. * * @param node The containing AST node + * @param property The AST node property being referenced * @param refNode The corresponding CST node - * @param refId The cross reference identifier like ':' * @param refText The cross reference text denoting the target AstNode * @returns the desired Reference node, whose behavior wrt. resolving the cross reference is implementation specific. */ From 17636a56f1445f7de44bf6ea0b2db321a7dd6a08 Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 23 Sep 2024 16:22:36 +0300 Subject: [PATCH 04/12] Replace comment with `satisfies` for better typing --- packages/langium/src/validation/document-validator.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/langium/src/validation/document-validator.ts b/packages/langium/src/validation/document-validator.ts index 804cb4765..6a94e642c 100644 --- a/packages/langium/src/validation/document-validator.ts +++ b/packages/langium/src/validation/document-validator.ts @@ -236,13 +236,13 @@ export function getDiagnosticRange(info: DiagnosticInfo Date: Mon, 23 Sep 2024 16:22:40 +0300 Subject: [PATCH 05/12] Fix typo in documentation comment --- packages/langium/src/generate/generator-node.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/langium/src/generate/generator-node.ts b/packages/langium/src/generate/generator-node.ts index 2b706325c..6a2cfd58c 100644 --- a/packages/langium/src/generate/generator-node.ts +++ b/packages/langium/src/generate/generator-node.ts @@ -14,7 +14,7 @@ export const EOL = (typeof process === 'undefined') ? '\n' : (process.platform = /** * Common type of expected results of functions contributing to code generation. - * Includes `undefined` for allowing contributing functions to explicitely contribute + * Includes `undefined` for allowing contributing functions to explicitly contribute * nothing, if required, in contrast to contributing empty strings, * which facilitates better formatting of the desired output, for example. */ From 0daa39313bcd6f7e32bb3660bf29cb54d4b9e0af Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 23 Sep 2024 16:26:17 +0300 Subject: [PATCH 06/12] Add workflow to build & deploy API docs on release --- .github/workflows/publish.yml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 61d6e4d2f..38d3e0aae 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -6,12 +6,15 @@ permissions: on: release: types: [published] + # To manually trigger a rebuild of the API docs if needed + workflow_dispatch: jobs: publish: name: Langium Publish runs-on: ubuntu-latest timeout-minutes: 20 + if: ${{ github.event_name == 'release' }} steps: - name: Checkout uses: actions/checkout@v3 @@ -56,3 +59,31 @@ jobs: PACKAGE_VERSION=`npm pkg get version --workspaces=false | tr -d \"` vsce package ovsx publish langium-vscode-$PACKAGE_VERSION.vsix -p ${{ secrets.OVSX_TOKEN }} + + docs: + name: Build and publish API docs + runs-on: ubuntu-latest + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Use Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + - name: Build API docs + run: | + npm ci + npm run docs -w langium + - name: Upload docs artifact + uses: actions/upload-pages-artifact@v3 + with: + path: packages/langium/docs + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From e21044a4c775421e66593ab03caf62ff427ad11c Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 23 Sep 2024 17:29:47 +0300 Subject: [PATCH 07/12] Use src tsconfig for API doc generation --- packages/langium/typedoc.json | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/langium/typedoc.json b/packages/langium/typedoc.json index 616192a71..a2ede0b45 100644 --- a/packages/langium/typedoc.json +++ b/packages/langium/typedoc.json @@ -7,6 +7,7 @@ "./src/node/index.ts", "./src/test/index.ts" ], + "tsconfig": "tsconfig.src.json", "out": "./docs", "includeVersion": true, "githubPages": true From 34f851b930dbcf4606cd7ec1bc824b3e9a89a536 Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 23 Sep 2024 18:16:25 +0300 Subject: [PATCH 08/12] Customize module names to correspond to exports --- packages/langium/src/generate/index.ts | 5 +++-- packages/langium/src/grammar/index.ts | 4 +++- packages/langium/src/index.ts | 4 +++- packages/langium/src/lsp/index.ts | 4 +++- packages/langium/src/node/index.ts | 4 +++- packages/langium/src/test/index.ts | 4 +++- packages/langium/typedoc.json | 5 +++++ 7 files changed, 23 insertions(+), 7 deletions(-) diff --git a/packages/langium/src/generate/index.ts b/packages/langium/src/generate/index.ts index ca70f6ff4..5464d3c29 100644 --- a/packages/langium/src/generate/index.ts +++ b/packages/langium/src/generate/index.ts @@ -2,11 +2,12 @@ * Copyright 2023 TypeFox GmbH * This program and the accompanying materials are made available under the * terms of the MIT License, which is available in the project root. - ******************************************************************************/ + * + * @module langium/generate + */ export * from './generator-node.js'; export type { SourceRegion, TextRegion, TraceRegion, TraceSourceSpec } from './generator-tracing.js'; export * from './node-joiner.js'; export * from './template-node.js'; export { expandToString, expandToStringLF, expandToStringLFWithNL, expandToStringWithNL, normalizeEOL } from './template-string.js'; - diff --git a/packages/langium/src/grammar/index.ts b/packages/langium/src/grammar/index.ts index 3544aa02f..0b303ded3 100644 --- a/packages/langium/src/grammar/index.ts +++ b/packages/langium/src/grammar/index.ts @@ -2,7 +2,9 @@ * Copyright 2023 TypeFox GmbH * This program and the accompanying materials are made available under the * terms of the MIT License, which is available in the project root. - ******************************************************************************/ + * + * @module langium/grammar + */ // This file contains Langium grammar language internals. // It is not supposed to be exported with the general `langium` export. diff --git a/packages/langium/src/index.ts b/packages/langium/src/index.ts index 654c6fb90..f2dba4647 100644 --- a/packages/langium/src/index.ts +++ b/packages/langium/src/index.ts @@ -2,7 +2,9 @@ * Copyright 2021 TypeFox GmbH * This program and the accompanying materials are made available under the * terms of the MIT License, which is available in the project root. - ******************************************************************************/ + * + * @module langium + */ export * from './default-module.js'; export * from './dependency-injection.js'; diff --git a/packages/langium/src/lsp/index.ts b/packages/langium/src/lsp/index.ts index 34b746669..81290ad0b 100644 --- a/packages/langium/src/lsp/index.ts +++ b/packages/langium/src/lsp/index.ts @@ -2,7 +2,9 @@ * Copyright 2021 TypeFox GmbH * This program and the accompanying materials are made available under the * terms of the MIT License, which is available in the project root. - ******************************************************************************/ + * + * @module langium/lsp + */ export * from './completion/completion-provider.js'; export * from './completion/follow-element-computation.js'; diff --git a/packages/langium/src/node/index.ts b/packages/langium/src/node/index.ts index c8a92c379..c4cc89d61 100644 --- a/packages/langium/src/node/index.ts +++ b/packages/langium/src/node/index.ts @@ -2,7 +2,9 @@ * Copyright 2022 TypeFox GmbH * This program and the accompanying materials are made available under the * terms of the MIT License, which is available in the project root. - ******************************************************************************/ + * + * @module langium/node + */ export * from './node-file-system-provider.js'; export * from './worker-thread-async-parser.js'; diff --git a/packages/langium/src/test/index.ts b/packages/langium/src/test/index.ts index 295468d0b..c8b4ae10a 100644 --- a/packages/langium/src/test/index.ts +++ b/packages/langium/src/test/index.ts @@ -2,6 +2,8 @@ * Copyright 2021 TypeFox GmbH * This program and the accompanying materials are made available under the * terms of the MIT License, which is available in the project root. - ******************************************************************************/ + * + * @module langium/test + */ export * from './langium-test.js'; diff --git a/packages/langium/typedoc.json b/packages/langium/typedoc.json index a2ede0b45..f89a53afa 100644 --- a/packages/langium/typedoc.json +++ b/packages/langium/typedoc.json @@ -1,4 +1,5 @@ { + "name": "Langium", "entryPoints": [ "./src/index.ts", "./src/generate/index.ts", @@ -9,6 +10,10 @@ ], "tsconfig": "tsconfig.src.json", "out": "./docs", + "navigation": { + "includeFolders": false + }, "includeVersion": true, + "sortEntryPoints": false, "githubPages": true } From 58770a8bb3ccbdcf8a311843c013ada982a0cc67 Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 30 Sep 2024 11:26:10 +0300 Subject: [PATCH 09/12] Add "remark" markers back instead of the tag --- packages/langium/src/parser/async-parser.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/langium/src/parser/async-parser.ts b/packages/langium/src/parser/async-parser.ts index 445a0c681..41daf6958 100644 --- a/packages/langium/src/parser/async-parser.ts +++ b/packages/langium/src/parser/async-parser.ts @@ -16,7 +16,7 @@ import { Emitter } from '../utils/event.js'; /** * Async parser that allows cancellation of the current parsing process. * - * The sync parser implementation is blocking the event loop, which can become quite problematic for large files. + * Remark: The sync parser implementation is blocking the event loop, which can become quite problematic for large files. * The default implementation is not actually async. It just wraps the sync parser in a promise. A real implementation would create worker threads or web workers to offload the parsing work. */ export interface AsyncParser { @@ -35,7 +35,7 @@ export interface AsyncParser { /** * Default implementation of the async parser which simply wraps the sync parser in a promise. * - * A real implementation would create worker threads or web workers to offload the parsing work. + * Remark: A real implementation would create worker threads or web workers to offload the parsing work. */ export class DefaultAsyncParser implements AsyncParser { From 7b22f04d0c2a689e97677fbb312f797bef28db41 Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 30 Sep 2024 11:35:59 +0300 Subject: [PATCH 10/12] Clarify where DiagnosticSeverity is defined --- packages/langium/src/validation/document-validator.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/langium/src/validation/document-validator.ts b/packages/langium/src/validation/document-validator.ts index 6a94e642c..7e3a487a3 100644 --- a/packages/langium/src/validation/document-validator.ts +++ b/packages/langium/src/validation/document-validator.ts @@ -233,6 +233,12 @@ export function getDiagnosticRange(info: DiagnosticInfo Date: Mon, 30 Sep 2024 13:44:59 +0300 Subject: [PATCH 11/12] Separate docs build & deploy to another workflow --- .github/workflows/docs.yml | 36 +++++++++++++++++++++++++++++++++++ .github/workflows/publish.yml | 31 ------------------------------ 2 files changed, 36 insertions(+), 31 deletions(-) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..eecd1bd62 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,36 @@ +name: Publish API docs + +permissions: + pages: write + id-token: write + +on: + release: + types: [published] + workflow_dispatch: + +jobs: + docs: + name: Build and publish API docs + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Use Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + - name: Build API docs + run: | + npm ci + npm run docs -w langium + - name: Upload docs artifact + uses: actions/upload-pages-artifact@v3 + with: + path: packages/langium/docs + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 38d3e0aae..61d6e4d2f 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -6,15 +6,12 @@ permissions: on: release: types: [published] - # To manually trigger a rebuild of the API docs if needed - workflow_dispatch: jobs: publish: name: Langium Publish runs-on: ubuntu-latest timeout-minutes: 20 - if: ${{ github.event_name == 'release' }} steps: - name: Checkout uses: actions/checkout@v3 @@ -59,31 +56,3 @@ jobs: PACKAGE_VERSION=`npm pkg get version --workspaces=false | tr -d \"` vsce package ovsx publish langium-vscode-$PACKAGE_VERSION.vsix -p ${{ secrets.OVSX_TOKEN }} - - docs: - name: Build and publish API docs - runs-on: ubuntu-latest - permissions: - pages: write # to deploy to Pages - id-token: write # to verify the deployment originates from an appropriate source - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Use Node.js - uses: actions/setup-node@v4 - with: - node-version: '18' - - name: Build API docs - run: | - npm ci - npm run docs -w langium - - name: Upload docs artifact - uses: actions/upload-pages-artifact@v3 - with: - path: packages/langium/docs - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 From 4b7d27347f867eec7df35b512078663bcdf5307c Mon Sep 17 00:00:00 2001 From: Abdelrahman Abounegm Date: Mon, 7 Oct 2024 09:47:23 +0300 Subject: [PATCH 12/12] Use the remarks block tag for remarks --- packages/langium/src/parser/async-parser.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/langium/src/parser/async-parser.ts b/packages/langium/src/parser/async-parser.ts index 41daf6958..0473aa9b0 100644 --- a/packages/langium/src/parser/async-parser.ts +++ b/packages/langium/src/parser/async-parser.ts @@ -16,7 +16,8 @@ import { Emitter } from '../utils/event.js'; /** * Async parser that allows cancellation of the current parsing process. * - * Remark: The sync parser implementation is blocking the event loop, which can become quite problematic for large files. + * @remarks + * The sync parser implementation is blocking the event loop, which can become quite problematic for large files. * The default implementation is not actually async. It just wraps the sync parser in a promise. A real implementation would create worker threads or web workers to offload the parsing work. */ export interface AsyncParser { @@ -35,7 +36,8 @@ export interface AsyncParser { /** * Default implementation of the async parser which simply wraps the sync parser in a promise. * - * Remark: A real implementation would create worker threads or web workers to offload the parsing work. + * @remarks + * A real implementation would create worker threads or web workers to offload the parsing work. */ export class DefaultAsyncParser implements AsyncParser {