支持自动更新ReadMe

This commit is contained in:
ProjectXero 2023-03-17 00:57:15 +08:00
parent d32b06e54e
commit a7500429c6
No known key found for this signature in database
GPG Key ID: C6021259092968FC
22 changed files with 428 additions and 143 deletions

View File

@ -11,21 +11,19 @@ d.ts 文件来源:[NPM组织 @minecraft](https://www.npmjs.com/search?q=%40min
## 准备
```
yarn
npm install
```
## 构建
```
yarn build
npm run build
```
## 更新原始文件Windows
## 更新原始文件
> 执行此步骤前请先提交更改!此步骤会将分支强制切换为 original
```
git checkout original
cd original
yarn install --no-lockfile
cd ..
.\translated\sync.cmd
npm run update
```

1
original/.npmrc Normal file
View File

@ -0,0 +1 @@
package-lock=false

View File

@ -1,8 +1,4 @@
{
"name": "original",
"version": "1.0.0",
"main": "index.js",
"license": "MIT",
"dependencies": {
"@minecraft/server": "beta",
"@minecraft/server-admin": "beta",

View File

@ -1 +0,0 @@
export * from "@minecraft/server-admin";

View File

@ -1 +0,0 @@
export * from "@minecraft/server-gametest";

View File

@ -1 +0,0 @@
export * from "@minecraft/server-net";

View File

@ -1 +0,0 @@
export * from "@minecraft/server-ui";

View File

@ -1 +0,0 @@
export * from "@minecraft/server";

View File

@ -1,28 +0,0 @@
{
"files": [
"server.ts",
"server-admin.ts",
"server-gametest.ts",
"server-net.ts",
"server-ui.ts"
],
"compilerOptions": {
"module": "commonjs",
"lib": ["es6"],
"target": "es6",
"noEmit": true,
"declaration": true
},
"typedocOptions": {
"name": "@minecraft",
"entryPoints": [
"server.ts",
"server-admin.ts",
"server-gametest.ts",
"server-net.ts",
"server-ui.ts"
],
"externalPattern": "",
"disableSources": true
}
}

167
package-lock.json generated Normal file
View File

@ -0,0 +1,167 @@
{
"name": "sapi-typedoc",
"version": "1.0.0",
"lockfileVersion": 2,
"requires": true,
"packages": {
"": {
"version": "1.0.0",
"license": "MIT",
"dependencies": {
"typedoc": "^0.23.23",
"typedoc-plugin-mdn-links": "^2.0.2",
"typescript": "^4.9.4"
},
"devDependencies": {}
},
"node_modules/balanced-match": {
"version": "1.0.2",
"license": "MIT"
},
"node_modules/brace-expansion": {
"version": "2.0.1",
"license": "MIT",
"dependencies": {
"balanced-match": "^1.0.0"
}
},
"node_modules/jsonc-parser": {
"version": "3.2.0",
"license": "MIT"
},
"node_modules/lunr": {
"version": "2.3.9",
"license": "MIT"
},
"node_modules/marked": {
"version": "4.2.5",
"license": "MIT",
"bin": {
"marked": "bin/marked.js"
},
"engines": {
"node": ">= 12"
}
},
"node_modules/minimatch": {
"version": "5.1.2",
"license": "ISC",
"dependencies": {
"brace-expansion": "^2.0.1"
},
"engines": {
"node": ">=10"
}
},
"node_modules/shiki": {
"version": "0.11.1",
"license": "MIT",
"dependencies": {
"jsonc-parser": "^3.0.0",
"vscode-oniguruma": "^1.6.1",
"vscode-textmate": "^6.0.0"
}
},
"node_modules/typedoc": {
"version": "0.23.23",
"license": "Apache-2.0",
"dependencies": {
"lunr": "^2.3.9",
"marked": "^4.2.4",
"minimatch": "^5.1.1",
"shiki": "^0.11.1"
},
"bin": {
"typedoc": "bin/typedoc"
},
"engines": {
"node": ">= 14.14"
},
"peerDependencies": {
"typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x"
}
},
"node_modules/typedoc-plugin-mdn-links": {
"version": "2.0.2",
"license": "MIT",
"peerDependencies": {
"typedoc": "0.22.x || 0.23.x"
}
},
"node_modules/typescript": {
"version": "4.9.4",
"license": "Apache-2.0",
"bin": {
"tsc": "bin/tsc",
"tsserver": "bin/tsserver"
},
"engines": {
"node": ">=4.2.0"
}
},
"node_modules/vscode-oniguruma": {
"version": "1.7.0",
"license": "MIT"
},
"node_modules/vscode-textmate": {
"version": "6.0.0",
"license": "MIT"
}
},
"dependencies": {
"balanced-match": {
"version": "1.0.2"
},
"brace-expansion": {
"version": "2.0.1",
"requires": {
"balanced-match": "^1.0.0"
}
},
"jsonc-parser": {
"version": "3.2.0"
},
"lunr": {
"version": "2.3.9"
},
"marked": {
"version": "4.2.5"
},
"minimatch": {
"version": "5.1.2",
"requires": {
"brace-expansion": "^2.0.1"
}
},
"shiki": {
"version": "0.11.1",
"requires": {
"jsonc-parser": "^3.0.0",
"vscode-oniguruma": "^1.6.1",
"vscode-textmate": "^6.0.0"
}
},
"typedoc": {
"version": "0.23.23",
"requires": {
"lunr": "^2.3.9",
"marked": "^4.2.4",
"minimatch": "^5.1.1",
"shiki": "^0.11.1"
}
},
"typedoc-plugin-mdn-links": {
"version": "2.0.2",
"requires": {}
},
"typescript": {
"version": "4.9.4"
},
"vscode-oniguruma": {
"version": "1.7.0"
},
"vscode-textmate": {
"version": "6.0.0"
}
}
}

View File

@ -3,8 +3,8 @@
"version": "1.0.0",
"license": "MIT",
"scripts": {
"build-original": "typedoc --tsconfig original/tsconfig.json --out dist_original --json dist_original/index.json",
"build": "typedoc --tsconfig translated/tsconfig.json --out dist --json dist/index.json --logLevel Verbose"
"build": "node ./script/build.js",
"update": "node ./script/update.js"
},
"dependencies": {
"typedoc": "^0.23.23",

41
script/build.js Normal file
View File

@ -0,0 +1,41 @@
const TypeDoc = require("typedoc");
const { resolve: resolvePath } = require("path");
const basePath = resolvePath(__dirname, "..");
const translatedPath = resolvePath(basePath, "translated");
const distPath = resolvePath(basePath, "dist");
async function build() {
const app = new TypeDoc.Application();
app.options.addReader(new TypeDoc.TSConfigReader());
app.bootstrap({
tsconfig: resolvePath(translatedPath, "tsconfig.json"),
githubPages: false,
logLevel: "Verbose"
});
const project = app.convert();
if (project) {
project.traverse((reflection) => {
if (reflection.sources) {
reflection.sources.forEach((source) => {
source.fileName = source.fileName.replace("translated", project.name);
});
}
return true;
});
await app.generateDocs(project, distPath);
} else {
throw new Error("Convert failed");
}
return project;
}
module.exports = {
build
};
if (require.main === module) {
build().catch((err) => {
console.error(err);
});
}

198
script/update.js Normal file
View File

@ -0,0 +1,198 @@
const { execSync } = require("child_process");
const { existsSync, readFileSync, copyFileSync, writeFileSync } = require("fs");
const { createRequire } = require("module");
const { resolve: resolvePath } = require("path");
const { URL } = require("url");
const { build } = require("./build.js");
const basePath = resolvePath(__dirname, "..");
const originalPath = resolvePath(basePath, "original");
const translatedPath = resolvePath(basePath, "translated");
const namespacePrefix = "@minecraft/";
const baseURL = "https://projectxero.top/sapi/";
function readPackageInfo(modulePath) {
const packageInfoPath = resolvePath(modulePath, "package.json");
if (existsSync(packageInfoPath)) {
try {
return JSON.parse(readFileSync(packageInfoPath, "utf-8"));
} catch(e) { /* ignore */ }
}
}
function findModule(moduleName, root) {
const localRequire = createRequire(resolvePath(root, "node_modules"));
const searchPaths = localRequire.resolve.paths(moduleName);
for (const searchPath of searchPaths) {
const modulePath = resolvePath(searchPath, moduleName);
const moduleDesc = readPackageInfo(modulePath);
if (moduleDesc && moduleDesc.name === moduleName) {
return modulePath;
}
}
}
function extractVersionInfo(versionString) {
const match = /^([\d.]+-\w+)\.([\d.]+)-(\w+)(\.\d+)?$/.exec(versionString);
if (match) {
const [, version, gameVersion, gamePreRelease, gameBuild] = match;
if (gameBuild) {
return { version, gamePreRelease, gameVersion: gameVersion + gameBuild };
}
return { version, gamePreRelease, gameVersion };
}
}
const KindString = [
// Project = 0x1,
"项目",
// Module = 0x2,
"模块",
// Namespace = 0x4,
"模块",
// Enum = 0x8,
"枚举",
// EnumMember = 0x10,
"枚举成员",
// Variable = 0x20,
"变量",
// Function = 0x40,
"函数",
// Class = 0x80,
"类",
// Interface = 0x100,
"接口",
// Constructor = 0x200,
"构造器",
// Property = 0x400,
"属性",
// Method = 0x800,
"方法",
// CallSignature = 0x1000,
"调用签名",
// IndexSignature = 0x2000,
"索引签名",
// ConstructorSignature = 0x4000,
"构造器签名",
// Parameter = 0x8000,
"参数",
// TypeLiteral = 0x10000,
"类型字面量",
// TypeParameter = 0x20000,
"类型参数",
// Accessor = 0x40000,
"访问器",
// GetSignature = 0x80000,
"Getter 签名",
// SetSignature = 0x100000,
"Setter 签名",
// ObjectLiteral = 0x200000,
"对象字面量",
// TypeAlias = 0x400000,
"类型别名",
// Reference = 0x800000
"引用"
];
function kindToString(kind) {
const result = [];
for (let i = 0; i < KindString.length; i++) {
if (kind & (1 << i)) {
result.push(KindString[i]);
}
}
return result.join("/");
}
async function main() {
// 1. 强制检出 original 分支
execSync("git checkout original", {
cwd: basePath,
stdio: "inherit"
});
// 2. 无视 lockfile 更新模块
execSync("npm install", {
cwd: originalPath,
stdio: "inherit"
});
// 3. 复制模块 d.ts 至翻译目录
const dependencies = readPackageInfo(originalPath).dependencies;
Object.keys(dependencies).forEach((moduleName) => {
if (moduleName.startsWith(namespacePrefix)) {
const pureModuleName = moduleName.slice(namespacePrefix.length);
const modulePath = findModule(moduleName, originalPath);
const packageInfo = readPackageInfo(modulePath);
const version = packageInfo.version;
console.log(`Copying d.ts for ${moduleName}@${version}`);
copyFileSync(
resolvePath(modulePath, "index.d.ts"),
resolvePath(translatedPath, `${pureModuleName}.d.ts`)
);
dependencies[moduleName] = version;
}
});
// 4. 生成一次文档
const project = await build();
// 5. 生成 README.md 。
const readMePath = resolvePath(translatedPath, "README.md");
const readMe = readFileSync(readMePath, "utf-8");
const summaryLines = [
"<!-- summary start -->",
"",
"|模块|版本|",
"| - | - |"
];
let gameVersion;
Object.entries(dependencies).forEach(([moduleName, version]) => {
const versionInfo = extractVersionInfo(version);
if (!versionInfo) {
throw new Error(`Invalid version for ${moduleName}@${version}`)
}
if (!gameVersion) gameVersion = versionInfo.gameVersion;
summaryLines.push(`|[${moduleName}](https://www.npmjs.com/package/${moduleName})|\`${versionInfo.version}\`|`);
});
summaryLines.push("");
summaryLines.push(`游戏版本号:\`${gameVersion}\``);
summaryLines.push("");
summaryLines.push("<!-- summary end -->");
const statusHeadLines = [
"<!-- status start -->",
"",
"|模块|进度|",
"| - | - |"
];
const statusLines = [];
project.children.forEach((moduleRef) => {
const moduleFullName = namespacePrefix + moduleRef.name;
const linkHref = moduleFullName.replace(/[@\/]/g, "");
statusHeadLines.push(`|[${moduleFullName}](#${linkHref})|0/${moduleRef.children.length}|`);
statusLines.push("");
statusLines.push(`### ${moduleFullName}`);
statusLines.push("");
statusLines.push("|名称|类型|状态|");
statusLines.push("| - | - | - |");
moduleRef.children.forEach((member) => {
const kindStr = kindToString(member.kind);
const url = new URL(member.url, baseURL);
statusLines.push(`|[\`${member.name}\`](${url})|${kindStr}|未翻译|`);
});
});
statusLines.unshift(...statusHeadLines);
statusLines.push("");
statusLines.push("<!-- status end -->");
const newReadMe = readMe
.replace(/<!-- summary start -->\n\n[^]+\n\n<!-- summary end -->/, summaryLines.join("\n"))
.replace(/<!-- status start -->\n\n[^]+\n\n<!-- status end -->/, statusLines.join("\n"));
writeFileSync(readMePath, newReadMe);
}
main().catch((err) => {
console.error(err);
});

View File

@ -2,6 +2,8 @@
Minecraft 脚本 API 文档。
<!-- summary start -->
|模块|版本|
| - | - |
|[@minecraft/server](https://www.npmjs.com/package/@minecraft/server)|`1.2.0-beta`|
@ -12,6 +14,8 @@ Minecraft 脚本 API 文档。
游戏版本号:`1.19.80.21`
<!-- summary end -->
通过 [typedoc](https://typedoc.org/) 基于 d.ts 生成。
目前正在翻译中。欢迎[参与翻译](#参与翻译)
@ -33,6 +37,8 @@ Minecraft 脚本 API 文档。
|`暂停中`|未完成翻译,因为译名讨论等原因暂停|
|`已完成`|已完成此部分的翻译|
<!-- status start -->
|模块|进度|
| - | - |
|[@minecraft/server](#minecraftserver)|0/299|
@ -397,3 +403,5 @@ Minecraft 脚本 API 文档。
|[`MessageFormResponse`](https://projectxero.top/sapi/classes/server_ui.MessageFormResponse.html)|类|未翻译|
|[`ModalFormData`](https://projectxero.top/sapi/classes/server_ui.ModalFormData.html)|类|未翻译|
|[`ModalFormResponse`](https://projectxero.top/sapi/classes/server_ui.ModalFormResponse.html)|类|未翻译|
<!-- status end -->

View File

@ -1,6 +0,0 @@
@echo off
copy %~dp0\..\original\node_modules\@minecraft\server\index.d.ts %~dp0\server.d.ts
copy %~dp0\..\original\node_modules\@minecraft\server-admin\index.d.ts %~dp0\server-admin.d.ts
copy %~dp0\..\original\node_modules\@minecraft\server-gametest\index.d.ts %~dp0\server-gametest.d.ts
copy %~dp0\..\original\node_modules\@minecraft\server-net\index.d.ts %~dp0\server-net.d.ts
copy %~dp0\..\original\node_modules\@minecraft\server-ui\index.d.ts %~dp0\server-ui.d.ts

View File

@ -1 +0,0 @@
export * from "../server-admin";

View File

@ -1 +0,0 @@
export * from "../server-gametest";

View File

@ -1 +0,0 @@
export * from "../server-net";

View File

@ -1 +0,0 @@
export * from "../server-ui";

View File

@ -1 +0,0 @@
export * from "../server";

View File

@ -1,7 +1,5 @@
{
"include": [
"ts/*"
],
"include": ["*"],
"compilerOptions": {
"module": "commonjs",
"lib": ["es6"],
@ -18,19 +16,17 @@
},
"typedocOptions": {
"name": "@minecraft",
"entryPoints": [
"ts/*"
],
"entryPoints": ["*.d.ts"],
"externalPattern": "",
"disableSources": true,
"customCss": "./assets/extra.css",
"externalSymbolLinkMappings": {
"typescript": {
"Promise": "https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise",
"Iterable": "https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Iteration_protocols",
"Iterator": "https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Iteration_protocols",
"IteratorResult": "https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Iteration_protocols"
"IteratorResult": "https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Iteration_protocols",
"Record": "https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type"
}
}
}
}
}

View File

@ -1,76 +0,0 @@
# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
# yarn lockfile v1
balanced-match@^1.0.0:
version "1.0.2"
resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-1.0.2.tgz#e83e3a7e3f300b34cb9d87f615fa0cbf357690ee"
integrity sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==
brace-expansion@^2.0.1:
version "2.0.1"
resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.1.tgz#1edc459e0f0c548486ecf9fc99f2221364b9a0ae"
integrity sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==
dependencies:
balanced-match "^1.0.0"
jsonc-parser@^3.0.0:
version "3.2.0"
resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.2.0.tgz#31ff3f4c2b9793f89c67212627c51c6394f88e76"
integrity sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==
lunr@^2.3.9:
version "2.3.9"
resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1"
integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==
marked@^4.2.4:
version "4.2.5"
resolved "https://registry.yarnpkg.com/marked/-/marked-4.2.5.tgz#979813dfc1252cc123a79b71b095759a32f42a5d"
integrity sha512-jPueVhumq7idETHkb203WDD4fMA3yV9emQ5vLwop58lu8bTclMghBWcYAavlDqIEMaisADinV1TooIFCfqOsYQ==
minimatch@^5.1.1:
version "5.1.2"
resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-5.1.2.tgz#0939d7d6f0898acbd1508abe534d1929368a8fff"
integrity sha512-bNH9mmM9qsJ2X4r2Nat1B//1dJVcn3+iBLa3IgqJ7EbGaDNepL9QSHOxN4ng33s52VMMhhIfgCYDk3C4ZmlDAg==
dependencies:
brace-expansion "^2.0.1"
shiki@^0.11.1:
version "0.11.1"
resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.11.1.tgz#df0f719e7ab592c484d8b73ec10e215a503ab8cc"
integrity sha512-EugY9VASFuDqOexOgXR18ZV+TbFrQHeCpEYaXamO+SZlsnT/2LxuLBX25GGtIrwaEVFXUAbUQ601SWE2rMwWHA==
dependencies:
jsonc-parser "^3.0.0"
vscode-oniguruma "^1.6.1"
vscode-textmate "^6.0.0"
typedoc-plugin-mdn-links@^2.0.2:
version "2.0.2"
resolved "https://registry.yarnpkg.com/typedoc-plugin-mdn-links/-/typedoc-plugin-mdn-links-2.0.2.tgz#5a6aa268950c41a1437b57e2c72ed77f8ba323d2"
integrity sha512-Fzjvfsj3rxvmZNqWRvq9JTGBkOkrPp0kBtvJCJ4U5Jm14OF1KoRErtmwgVQcPLA5Xs8h5I/W4uZBaL8SDHsgxQ==
typedoc@^0.23.23:
version "0.23.23"
resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.23.23.tgz#9cf95b03d2d40031d8978b55e88b0b968d69f512"
integrity sha512-cg1YQWj+/BU6wq74iott513U16fbrPCbyYs04PHZgvoKJIc6EY4xNobyDZh4KMfRGW8Yjv6wwIzQyoqopKOUGw==
dependencies:
lunr "^2.3.9"
marked "^4.2.4"
minimatch "^5.1.1"
shiki "^0.11.1"
typescript@^4.9.4:
version "4.9.4"
resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.9.4.tgz#a2a3d2756c079abda241d75f149df9d561091e78"
integrity sha512-Uz+dTXYzxXXbsFpM86Wh3dKCxrQqUcVMxwU54orwlJjOpO3ao8L7j5lH+dWfTwgCwIuM9GQ2kvVotzYJMXTBZg==
vscode-oniguruma@^1.6.1:
version "1.7.0"
resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz#439bfad8fe71abd7798338d1cd3dc53a8beea94b"
integrity sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==
vscode-textmate@^6.0.0:
version "6.0.0"
resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-6.0.0.tgz#a3777197235036814ac9a92451492f2748589210"
integrity sha512-gu73tuZfJgu+mvCSy4UZwd2JXykjK9zAZsfmDeut5dx/1a7FeTk0XwJsSuqQn+cuMCGVbIBfl+s53X4T19DnzQ==