docs: use GPT to polish the document language

northword · Dec 19, 2024 · 8b5c473 · 8b5c473
1 parent 2666a6e
commit 8b5c473
Show file tree

Hide file tree

Showing 5 changed files with 95 additions and 86 deletions.
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ For best practices regarding this package, please refer to [zotero-plugin-templa
 
 ## Documentation
 
-[Read the Docs to Learn More.](https://northword.github.io/zotero-plugin-scaffold)
+[Read the Docs to Learn More](https://northword.github.io/zotero-plugin-scaffold).
 
 ## Contributing
 

diff --git a/docs/index.md b/docs/index.md
@@ -5,23 +5,23 @@ layout: home
 hero:
   name: "Scaffold"
   text: "Zotero Plugins"
-  tagline: The Modern Development Experience for Zotero Plugins
+  tagline: "The Modern Development Framework for Zotero Plugins"
   actions:
     - theme: brand
-      text: Quick Start
+      text: "Quick Start"
       link: /quick-start
 
 features:
-  - title: Dev Serve
-    details: Auto reload your plugin when source code changed
+  - title: "Dev Serve"
+    details: "Automatically reload your plugin whenever the source code changes."
     link: /serve
-  - title: Build Plugin
-    details: TypeScript supported, many utils builders, and pack code to xpi
+  - title: "Build Plugin"
+    details: "Supports TypeScript, provides utility builders, and packages your code into an XPI file."
     link: /build
-  - title: Test plugin
-    details: Out-of-the-box test kits
+  - title: "Test Plugin"
+    details: "Comes with ready-to-use testing kits."
     link: /test
-  - title: Release
-    details: Auto bump version, and publish your plugin to GitHub
+  - title: "Release"
+    details: "Automatically bump the version and publish your plugin to GitHub."
     link: /release
 ---
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -1,39 +1,45 @@
 # Quick Start
 
-## Using in a blank project
+## Using in a Blank Project
 
-::: details WIP: Not yet implemented
+::: details WIP: Not Yet Implemented
 
 ```bash
-# npm
+# Using npm
 npx zotero-plugin create
-# pnpm
+
+# Using pnpm
 pnpm dlx zotero-plugin create
 ```
 
 :::
 
-## Using in an existing project
+## Using in an Existing Project
 
-### 01. Install
+### 01. Install the Package
+
+You can install `zotero-plugin-scaffold` using your preferred package manager:
 
 ```bash
+# npm
 npm install -D zotero-plugin-scaffold
 
+# yarn
 yarn add -D zotero-plugin-scaffold
 
+# pnpm
 pnpm add -D zotero-plugin-scaffold
 ```
 
-### 02. Create a config file
+### 02. Create a Configuration File
 
-The configuration file needs to be stored in the following location.
+The configuration file should be placed at one of the following locations:
 
 ```bash
-zotero-plugin.config.ts  # also avaliable in *.js  *.mjs  *.cjs  *.ts
+zotero-plugin.config.ts  # Also supported: *.js, *.mjs, *.cjs, *.ts
 ```
 
-You can import helper `defineConfig` to get type hints. If no value is specified for an optional property, the default value will be used.
+You can use the `defineConfig` helper to enable type hints. Optional properties will default to predefined values if not explicitly specified.
 
 ```ts
 import { defineConfig } from "zotero-plugin-scaffold";
@@ -54,15 +60,15 @@ export default defineConfig({
 });
 ```
 
-Full config please refrence in [src/types](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts).
+For a full list of configuration options, refer to the [type definitions](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts).
 
-### 03. Create a env file
+### 03. Create an Environment File
 
-This file defines Zotero's runtime configuration such as binary paths, profile paths, and environment variables required for Node scripts to run.
+Define Zotero’s runtime configuration (e.g., binary paths, profile paths, and environment variables) in a `.env` file.
 
 ::: warning
 
-NOTE: Do not check-in this file to the repository!
+Do not commit this file to your repository!
 
 :::
 
@@ -71,17 +77,19 @@ NOTE: Do not check-in this file to the repository!
 ```
 
 ```ini
-# The path of the Zotero binary file.
-# The path is `*/Zotero.app/Contents/MacOS/zotero` for macOS.
-ZOTERO_PLUGIN_ZOTERO_BIN_PATH = /path/to/zotero.exe
-
-# The path of the profile used for development.
-# Start the profile manager by `/path/to/zotero.exe -p` to create a profile for development.
-# @see https://www.zotero.org/support/kb/profile_directory
-ZOTERO_PLUGIN_PROFILE_PATH = /path/to/profile
+# Path to the Zotero binary file.
+# For macOS, the path is typically `*/Zotero.app/Contents/MacOS/zotero`.
+ZOTERO_PLUGIN_ZOTERO_BIN_PATH=/path/to/zotero.exe
+
+# Path to the profile used for development.
+# To create a profile for development, start the profile manager with `/path/to/zotero.exe -p`.
+# More info: https://www.zotero.org/support/kb/profile_directory
+ZOTERO_PLUGIN_PROFILE_PATH=/path/to/profile
 ```
 
-### 04. Add scripts to package.json
+### 04. Add Scripts to `package.json`
+
+Add the following scripts for development:
 
 ```json
 {
@@ -93,20 +101,27 @@ ZOTERO_PLUGIN_PROFILE_PATH = /path/to/profile
 }
 ```
 
-### 05. Run
+### 05. Run the Plugin
+
+Use the following commands to start development or build the plugin:
 
 ```bash
+# Start the development server
 pnpm run start
+
+# Build the plugin
 pnpm run build
 ```
 
-## Using in NodeJS code
+## Using in Node.js Code
+
+You can also use `zotero-plugin-scaffold` programmatically in your Node.js scripts:
 
 ```ts
 import { Build, Config } from "zotero-plugin-scaffold";
 
 const config = await Config.loadConfig();
 
-const Builder = new Build(config);
-await Builder.run();
+const builder = new Build(config);
+await builder.run();
 ```
diff --git a/docs/release.md b/docs/release.md
@@ -1,9 +1,9 @@
 # Release
 
-我们都知道，对于一个插件的发布，我们需要手动修改 `manifest.json` 中的 `version` 值，然后将其打包，上传到某个地方，随后，我们还需要更新 `update.json` 中的版本号和链接。
+When releasing a plugin, we typically need to manually update the `version` value in `manifest.json`, package the plugin, upload it somewhere, and then update the `version` and link in `update.json`.
 
-为了保持 Git 记录，我们在修改 version 值后，还需要提交代码并为这个提交添加 tag。
+To maintain Git history, we also need to commit the changes and add a tag to the commit after updating the version.
 
-—— 这太麻烦了！
+— It’s too tedious!
 
-在 Scaffold 中，你只需要运行 `zotero-plugin release`，然后选择一个你需要的版本号，一切都将自动运行。
+With Scaffold, all you need to do is run `zotero-plugin release` and select the desired version number. Everything else will be handled automatically.
diff --git a/docs/test.md b/docs/test.md
@@ -1,50 +1,44 @@
 # Testing
 
-`zotero-plugin-scaffold` can run [Mocha](https://mochajs.org/) / [Chai](https://www.chaijs.com/)-based tests against a live Zotero instance via a proxy plugin.
+`zotero-plugin-scaffold` enables testing with [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) in a live Zotero instance through a proxy plugin.
 
-A temporary profile and data directory will be created when launching Zotero, so tests can be run locally on the system Zotero installation.
+When running tests, a temporary profile and data directory are created, allowing the tests to execute locally on the installed Zotero application.
 
-## Why
+## Why Use This Approach?
 
-Since Zotero is a browser environment and has a lot of private APIs, if we use the mainstream Node-side testing scheme, we will inevitably need to mock a lot of methods, which will distort the test results.
+Zotero operates in a browser-like environment with many private APIs. Using conventional Node.js testing frameworks would require extensive mocking, leading to distorted test results.
 
-In Scaffold, we use mocha as the testing framework, which is a simple but flexible enough testing framework for the browser side. We also use chai as an assertion library.
+To address this, Scaffold uses Mocha as a lightweight yet flexible browser-compatible testing framework, complemented by Chai for assertions.
 
-When we start a test, we generate a temporary plugin in `.scaffold/test/resource/` that we use to run the test. Iterate through the test files in the `test.entries` directory and compile them in `.scaffold/test/resource/content`.
-
-When Zotero starts up, it loads your plugin and the test plugin that was just generated separately, so we have complete access to all the APIs and can use them for testing.
+Tests are executed via a temporary plugin generated in `.scaffold/test/resource/`. The test files in the `test.entries` directory are compiled into `.scaffold/test/resource/content`. When Zotero launches, it loads both the primary plugin and the generated test plugin, providing full access to all APIs needed for testing.
 
 ## Usage
 
 ### Configuring Test Options
 
-After configuring your project to be built with `zotero-plugin-scaffold`, add a `test` object to your configuration:
+After setting up your project with `zotero-plugin-scaffold`, add a `test` object to your configuration:
 
-```ts twoslash
+```ts
 export default defineConfig({
   // ...
   test: {
-    // Directories containing *.spec.js tests
+    // Directories containing *.spec.js test files
     entries: ["test"],
-    // Exit Zotero when the test is finished.
+    // Exit Zotero after the tests complete
     exitOnFinish: true,
-    // Function string that returns the initialization status of the plugin.
-    // If set, the test will wait until the function returns true before running the test.
-    // e.g.
-    //   if your plugin created a `MyPlugin` object beneath `Zotero` and it set an
-    //  `initialized` field to `true` at the end of its `startup` bootstrap method...
+    // Function string that returns the plugin's initialization status
+    // The test waits until this function returns true
+    // Example: if your plugin sets `Zotero.MyPlugin.initialized` to `true` in its `startup` method...
     waitForPlugin: `() => Zotero.MyPlugin.initialized`,
   }
 });
 ```
 
 ::: tip
-
-See the `TestConfig` interface in [`src/types/config.ts`](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts) for full documentation.
-
+Refer to the `TestConfig` interface in [`src/types/config.ts`](https://github.com/northword/zotero-plugin-scaffold/blob/main/src/types/config.ts) for complete documentation.
 :::
 
-Add a script to `package.json`:
+Add a `test` script to your `package.json`:
 
 ```json
 {
@@ -56,27 +50,29 @@ Add a script to `package.json`:
 
 ### Install Mocha and Chai
 
-We recommend that you install `mocha.js` locally as a development dependency, as this will avoid some potential dependency conflicts:
+Install `mocha` as a local development dependency to avoid potential conflicts:
 
 ```bash
 npm install -D mocha @types/mocha @types/chai
 ```
 
-When Scaffold detects your locally installed mocha, it will automatically use your installed mocha, otherwise Scaffold will get the latest version of mocha from NPM.
+If Scaffold detects a local `mocha` installation, it will use it. Otherwise, it fetches the latest version from NPM. Due to unresolved ESM import issues with Chai, Scaffold always uses the remote version.
 
-Since the ESM import issue for Chai has not been resolved, chai will always use the remote version.
+Cached versions of `mocha` and `chai` are stored in `.scaffold/cache`. Delete this cache if you need to force an update.
 
-The mocha and chai downloaded from the remote will be cached in the `.scaffold/cache` directory, and you can delete the cache if you need to in order to force Scaffold to update their versions.
+### Writing Test Cases
 
-### Write Your Test Cases
+Write test cases using [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) syntax.
 
-You can then write your test file, see [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) for syntax.
+### Running Tests
 
-### Run Test
+After writing your test cases, run them using:
 
-一旦你完成测试代码的编写，你可以通过 `npm run test` 来启动测试。
+```bash
+npm run test
+```
 
-`zotero-plugin test` 也提供了一些命令行参数，以便你可以覆盖配置文件中的设置，你可以通过 `zotero-plugin test --help` 来查看：
+You can override configuration settings with CLI parameters. Use `zotero-plugin test --help` to view available options:
 
 ```bash
 $ pnpm zotero-plugin test --help
@@ -92,26 +88,24 @@ Options:
 
 ## Watch Mode
 
-In watch mode, Scaffold will:
+In watch mode, Scaffold automatically:
 
-- When the source code changes, it will automatically recompile the source code, reload the plugins and re-run the tests;
-- When the test code changes, it will automatically re-run the tests;
+- Recompiles source code, reloads plugins, and reruns tests when the source changes.
+- Reruns tests when test files are modified.
 
-This feature is not yet complete.
+This feature is still under development.
 
-## Run Test on CI
+## Running Tests on CI
 
-Most of the time, we want tests to run automatically on CI services such as GitHub Actions, for which we provide `headless` mode.
+To run tests automatically on CI services like GitHub Actions, Scaffold provides a `headless` mode.
 
-In general, when we detect that you are running tests on a CI service, we will automatically enable headless mode. If you have a need to use headless locally, you just need to pass `headless` in the cli parameter or set `test.headless: true` in the configuration.
+By default, Scaffold enables headless mode on CI services. To enable it locally, pass `headless` as a CLI parameter or set `test.headless: true` in the configuration.
 
 ::: warning
-
-Scaffold's built-in headless mode is only supported on Ubuntu 22.04, 24.04. If you are using a different Linux distribution, manually configure the headless environment, set Scaffold's `test.headless` to `false`, and start the test using something like `xvfb-run npm run test`, etc.
-
+Scaffold's built-in headless mode supports only Ubuntu 22.04 and 24.04. For other Linux distributions, manually configure a headless environment, set `test.headless` to `false`, and use tools like `xvfb-run npm run test`.
 :::
 
-For tests running on GitHub Actions, this is a typical workflow template:
+For GitHub Actions, use the following workflow template:
 
 ```yaml
 name: test
@@ -126,17 +120,17 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
 
-      - name: Install deps
+      - name: Install dependencies
         run: npm install
 
-      - name: Test
+      - name: Run tests
         run: npm test
 ```