update docs

semojs · Mar 5, 2024 · 9897e18 · 9897e18
1 parent 15f29f4
commit 9897e18
Show file tree

Hide file tree

Showing 18 changed files with 1,180 additions and 442 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -1,4 +1,5 @@
-const host = process.env.NODE_ENV === 'development' ? 'localhost:8080' : 'semo.js.org'
+const host =
+  process.env.NODE_ENV === 'development' ? 'localhost:8080' : 'semo.js.org'
 
 module.exports = {
   base: '/',
@@ -9,13 +10,13 @@ module.exports = {
     '/': {
       lang: 'zh-CN', // 将会被设置为 <html> 的 lang 属性
       title: 'Semo',
-      description: '一个Node项目命令行开发规范'
+      description: '一个Node项目命令行开发规范',
     },
     '/en/': {
       lang: 'en-US',
       title: 'Semo',
-      description: 'A Node.js CLI building rules.'
-    }
+      description: 'A Node.js CLI building rules.',
+    },
   },
   themeConfig: {
     repo: 'semojs/semo',
@@ -30,7 +31,7 @@ module.exports = {
           { text: '首页', link: '/' },
           { text: '指南', link: '/guide/' },
           { text: '用法', link: '/usage/' },
-          { text: '参考', link: `http://${host}/typedoc/` }
+          { text: '参考', link: `http://${host}/typedoc/` },
         ],
         sidebarDepth: 1,
         sidebar: [
@@ -45,7 +46,7 @@ module.exports = {
               '/guide/config/',
               '/guide/hook/',
               '/guide/plugin/',
-            ]
+            ],
           },
           {
             title: '用法',
@@ -56,25 +57,22 @@ module.exports = {
               '/usage/integration/',
               '/usage/solution/',
               '/usage/distribution/',
-            ]
+            ],
           },
           {
             title: '社区',
             collapsable: false,
-            children: [
-              '/community/contrib/',
-              '/community/qa/',
-            ]
-          }
-        ]
+            children: ['/community/contrib/', '/community/qa/'],
+          },
+        ],
       },
       '/en/': {
         editLinkText: 'Help improve this page',
         nav: [
           { text: 'Home', link: '/en/' },
           { text: 'Guide', link: '/en/guide/' },
-          { text: 'Usage', link: '/usage/' },
-          { text: 'Reference', link: `http://${host}/typedoc/` }
+          { text: 'Usage', link: '/en/usage/' },
+          { text: 'Reference', link: `http://${host}/typedoc/` },
         ],
         sidebarDepth: 1,
         sidebar: [
@@ -85,34 +83,30 @@ module.exports = {
               '/en/guide/',
               '/en/guide/quickstart/',
               '/en/guide/core-commands/',
-              '/guide/custom-commands/',
+              '/en/guide/custom-commands/',
               '/en/guide/config/',
-              '/guide/hook/',
-              '/guide/plugin/',
-            ]
+              '/en/guide/hook/',
+              '/en/guide/plugin/',
+            ],
           },
           {
             title: 'Usage',
             collapsable: false,
             children: [
-              '/usage/',
-              '/usage/plugin/',
-              '/usage/integration/',
-              '/usage/solution/',
-              '/usage/distribution/',
-            ]
+              '/en/usage/',
+              '/en/usage/plugin/',
+              '/en/usage/integration/',
+              '/en/usage/solution/',
+              '/en/usage/distribution/',
+            ],
           },
           {
             title: 'Community',
             collapsable: false,
-            children: [
-              '/community/contrib/',
-              '/community/qa/',
-            ]
-          }
-        ]
-      }
-    }
-  }
-
+            children: ['/en/community/contrib/', '/en/community/qa/'],
+          },
+        ],
+      },
+    },
+  },
 }
diff --git a/docs/en/README.md b/docs/en/README.md
@@ -1,29 +1,29 @@
 ---
 home: true
-actionText: Get started →
-actionLink: /en/guide/quickstart/
+actionText: Quick Start →
+actionLink: /guide/quickstart/
 features:
-- title: Consistency
-  details: No matter what framework used and how structured, you can use this package to implement consistent command line scripts.
-- title: Flexibility
-  details: You can extend by plugins, you can override commands, config, and you can hook with core or other plugins.
-- title: Efficiency
-  details: The command rule is simple, so it easy to use, if you use it frequently, it can dramatically improve you performant.
-footer: Enterprise level Node CLI building rules
+- title: Consistent
+  details: Regardless of the framework used in the Node project or how abstraction is layered, this framework can be used to implement command-line scripts with a unified style.
+- title: Extensible
+  details: Plugins can be extended, commands can be overridden, configurations can be overwritten, and hook mechanisms can interact with hooks defined by built-in or third-party plugins.
+- title: Efficient
+  details: Due to its simple rules, development efficiency is high, and due to frequent use, work efficiency is high.
+footer: Standardized Command Line System Construction Specification for Enterprise-level Node Projects
 ---
 
 ```bash
-# Install globally to your local machine.
+# For local environment, global installation is generally recommended
 npm install -g @semo/cli
 semo help
 
-# Install to your project
+# First integration in the project
 cd YOUR_PROJECT
 npm install @semo/cli
 semo init
 semo generate command test
 
-# Use application convention to reduce first level commands
+# Using the application command line specification
 npm install semo-plugin-application
 semo generate command application/test --extend=application
 ```
diff --git a/docs/en/community/contrib/README.md b/docs/en/community/contrib/README.md
@@ -0,0 +1,23 @@
+# How to Contribute
+
+## Adoption and Use
+
+There are many choices for standardizing command-line implementation methods. In general, having a standard is better than not having one. If your team already has its own standards, then there's no need to adopt `Semo`'s standard. However, if your team hasn't standardized command-line operations before, you might want to give `Semo` a try. If you happen to favor `yargs`, some of `Semo`'s ideas might be insightful to you as well.
+
+`Semo` can be used in many areas, including development, testing, deployment, operations, and even non-business scenarios like web scraping.
+
+## Writing Documentation
+
+The documentation for `Semo` needs to be gradually improved with everyone's help. Some usage tips may not be mentioned in the documentation yet, so feel free to explore and share your findings.
+
+## Writing Plugins
+
+There are two types of plugins here. One type can play a role in technology accumulation in enterprise-level projects by encapsulating common operations and logic into plugins. The other type is personal creative plugins, unrelated to business, which can implement and share creative works.
+
+## Contributing Code
+
+Contributing code, whether it's for using in business projects, creating creative plugins, or participating in the development of core features, is a great way to give back to the community.
+
+## Helping Identify Issues
+
+Whether it's code or documentation, many issues may remain undiscovered, such as outdated code, typos in documentation, or inaccuracies due to continuous improvement and upgrades. It requires everyone's collaborative efforts to maintain and improve them.
diff --git a/docs/en/community/qa/README.md b/docs/en/community/qa/README.md
@@ -0,0 +1,80 @@
+---
+sidebar: auto
+---
+# Frequently Asked Questions
+
+## Why is `Semo` so slow and how can it be optimized?
+
+Compared to some scripts with relatively simple and pure logic, Semo considers many flexible settings, including but not limited to multi-layer scanning of plugins, configuration override rules, hook mechanisms, and so on. Among them, the most significant impact comes from the IO burden of plugin scanning. Currently, some optimizations have been made (such as introducing internal caching), which have had some effects. If the scanning results of plugins are thoroughly persisted, further performance improvements can be achieved, but this is a double-edged sword and requires consideration of update mechanisms. Continuous optimization will be carried out in the future.
+
+Furthermore, up to now, various possibilities of `Semo` in business development are being explored, and the temporary performance issues have not had a significant impact. Therefore, more emphasis is placed on exploring and compatibility with various possibilities.
+
+Speed can be further improved by narrowing down the scope of plugin scanning:
+
+```bash
+semo status --disable-global-plugin --disable-home-plugin
+```
+
+If you don't want to enter it every time, you can put it in the `.semorc.yml` file:
+
+```yaml
+--disable-global-plugin: true
+--disable-home-plugin: true
+```
+
+or
+
+```yaml
+disableGlobalPlugin: true
+disableHomePlugin: true
+```
+
+## Can `Semo` directly run `Typescript` commands?
+
+Simply put, no, if it could, wouldn't it be `Deno`? However, it is possible under special conditions. Here are the steps:
+
+**1. There should be `typescript` and `ts-node` packages in the project**
+
+```bash
+yarn add typescript ts-node -D
+```
+
+**2. Initialize tsconfig.json**
+
+```bash
+npx tsc --init
+```
+
+**Configuration should be modified according to needs. The minimum required configuration here is:**
+
+```json
+"target": "es6"
+```
+
+The reason is that the converted code contains `async/await`.
+
+**3. Configure a scripts command in package.json**
+
+```json
+"scripts": {
+    "semo": "node --require ts-node/register ./node_modules/@semo/cli/lib/bin.js"
+}
+```
+
+**4. Modify `.semorc.yml`**
+
+Add support for Typescript
+
+```yaml
+typescript: true
+```
+
+**5. Finally, create a TypeScript command line script**
+
+```bash
+semo g command test
+yarn semo test
+```
+
+This approach is more suitable for defining local commands. The performance is slower than executing compiled code, but the development experience is better. Generally, the most commonly used method is to let Semo execute the compiled commands.
+
diff --git a/docs/en/guide/README.md b/docs/en/guide/README.md
@@ -1,28 +1,28 @@
 # Introduction
 
-Semo is a CLI framework, based on excellent `yargs`. Semo do not want to do CLI parsing jobs, defining commands, but giving rules about how to use `yargs`, so it's easy to used in your Node.js projects, provide consitent CLI style and flexibility. 
+Semo is a command-line development framework, built on top of the excellent `yargs` package with encapsulation and extension. Semo aims not to solve problems such as parsing command-line options and parameters, defining commands, and triggering commands, but to standardize and specify how to implement them in business scenarios. This ensures a consistent command-line architecture for numerous Node microservice projects within a company, while also providing various extension features.
 
 ## Principles
 
-- **Consistency**: No matter what framework used and how structured, you can use this package to implement consistent command line scripts.
-- **Flexibility**: You can extend by plugins, you can override commands, config, and you can hook with core or other plugins.
-- **Efficiency**: The command rule is simple, so it easy to use, if you use it frequently, it can dramatically improve you performant.
+- **Consistency**: Regardless of the framework used in Node projects or how abstraction is layered, this framework can be used to implement command-line scripts with a unified style.
+- **Extensibility**: Plugins can be extended, commands can be overridden, configurations can be overwritten, and the hook mechanism can interact with hooks defined by built-in or third-party plugins.
+- **Efficiency**: Simple to get started with, high development efficiency, consistent style, high maintenance efficiency, frequent use, and high work efficiency.
 
 ## Features
 
-- Core concepts are less, just plugin, command, script, config, and hook.
-- Plugin, command, config all can be extended or overriden.
-- Provide a useful REPL environment, support `await`.
-- Add sub commands for other plugins's commands.
-- Provide a simple code generator rule, support plugin, command generator.
-- Plugin is by name convention.
+- Few but powerful core concepts, including plugins, commands, scripts, configurations, hooks, etc.
+- Plugins, commands, and configurations can be extended or overridden according to conventions.
+- Provides an extensible REPL environment and supports `await`.
+- Child commands can be added to commands defined by other plugins.
+- Provides a simple code generation mechanism; basic plugin, command, and script boilerplate code can be automatically generated, with support for extensions.
+- Supports plugins with npm organization package name format.
 
-## Name story
+## Origin of the Name
 
-Semo is from World language, the meaning is like `tinder` in English.
+As is well known, naming is hard. Semo is a concept born out of the spark in my mind, translated from various languages, meaning "seed" in Esperanto, symbolizing a starting point and hope.
 
-## About this doc
+## Conventions
 
-- Semo support `Typescript` and `Javascript`, but demo code in this doc mostly use `Typescript` style.
-- By default, suppose `semo` and `yarn` are installed already.
-- This is a personal project, only tested on `Mac` and `Linux`, but not `Windows`.
+- All example code is based on `Typescript`. Although the core of `Semo` is also written in `Typescript`, `Semo` supports projects written purely in `js`, as explained in the configuration management section.
+- The documentation assumes that `semo` and `yarn` are globally installed in the environment and does not explicitly mention them in specific chapters.
+- The development environment of this project is `Mac`, and the runtime environment is either the local machine or the container environment online. It has not been tested on `Windows` and may have compatibility issues.