Merge branch 'docs'

abgox · May 22, 2024 · c6d9a72 · c6d9a72
2 parents b720cd0 + f66f965
commit c6d9a72
Show file tree

Hide file tree

Showing 10 changed files with 481 additions and 7 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -2,7 +2,7 @@ import { defineConfig } from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  base: "/PSCompletions",
+  base: "/PSCompletions/",
   title: "PSCompletions(psc)",
   locales: {
     "en-US": {
@@ -19,6 +19,36 @@ export default defineConfig({
   themeConfig: {
     socialLinks: [
       { icon: 'github', link: 'https://github.com/abgox/PSCompletions' }
-    ]
-  }
+    ],
+    search: {
+      provider: 'local',
+      options: {
+        locales: {
+          "zh-CN": {
+            translations: {
+              button: {
+                buttonText: '搜索文档',
+                buttonAriaLabel: '搜索文档'
+              },
+              modal: {
+                displayDetails: "显示详细列表",
+                noResultsText: '无法找到相关结果',
+                resetButtonTitle: '清除查询条件',
+                footer: {
+                  selectText: '选择',
+                  navigateText: '切换',
+                  closeText: "关闭"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    outline: "deep",
+    footer: {
+      message: 'Released under the <a href="https://github.com/abgox/PSCompletions/blob/main/LICENSE">MIT License</a>.',
+      copyright: 'Copyright © 2023-present <a href="https://github.com/abgox">abgox</a>'
+    }
+  },
 })
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -13,7 +13,11 @@ export default {
   },
   enhanceApp() {
     try {
+      let langs = ['en-US', 'zh-CN']
       let lang = navigator.language
+      if (!langs.includes(lang)) {
+        lang = langs[0]
+      }
       if (/\/PSCompletions\/?$/.test(location.pathname)) {
         location.href += lang
       }

diff --git a/docs/en-US/command/index.md b/docs/en-US/command/index.md
@@ -0,0 +1,11 @@
+---
+title: About PSCompletions(psc) command
+next:
+    text: About PR (Pull Request)
+    link: '../contribute/index.md'
+---
+
+-   Waiting...
+    -   You can trigger completion by running `psc`, then learn about them by completion tip.
+    -   View the README file of PSCompletions.
+    -   Enter 'psc' and press 'Enter' to print some module information
diff --git a/docs/en-US/completion/index.md b/docs/en-US/completion/index.md
@@ -0,0 +1,155 @@
+---
+title: About the structure of json file
+next:
+    text: About PR (Pull Request)
+    link: '../contribute/index.md'
+---
+
+# About the structure of json file
+
+```json
+{
+	"root": [],
+	"options": [],
+	"common_options": [],
+	"info": {},
+	"config": []
+}
+```
+
+-   The json file uses a schema structure to ensure that the json content is correct and complete.
+    -   You can learn about these properties by hovering over the prompts
+-   In fact, it is very simple, you can refer to the existing json file.
+
+## Properties
+
+### 1. `root`
+
+-   The type of value: array
+-   The most core attribute (usually)
+
+    -   Each item in the array is an object
+    -   Object available attribute: `name`(required)、`alias`、`symbol`、`next`、`options`、`tip`
+    -   In vscode, with schema, it's easy to understand.
+    -   The values of `next` and `options` are also arrays, almost identical to `root`.
+        -   Difference: The `options` attribute is not allowed in `options`.
+    -   In most cases, you don't need to think about defining `symbol` because `symbol` will automatically add some value to the symbols depending on context
+        -   When the completion item has `next`, `SpaceTab` is automatically added.
+        -   The `symbol` attribute in `options` automatically adds the `OptionTab`.
+    -   Some Cases where `Symbol` needs to be added manually.
+
+        -   When several preset values are needed in `options`
+
+            -   ```json
+                {
+                	"name": "reset",
+                	"options": [
+                		{
+                			"name": "--soft",
+                			"symbol": ["WriteSpaceTab", "SpaceTab"]
+                		}
+                	]
+                }
+                ```
+
+        -   When completion uses `hooks` to add some dynamic completion items.
+            -   ```json
+                {
+                	"name": "rm",
+                	"symbol": "SpaceTab"
+                }
+                ```
+
+### 2. `options`
+
+-   The type of value: array
+-   Same as the `options` for each item in `root`.
+-   ```json
+    {
+    	"options": [
+    		{
+    			"name": "--version",
+    			"alias": ["-v"],
+    			"tip": "Show current version"
+    		}
+    	]
+    }
+    ```
+
+### 3. `common_options`
+
+-   The type of value: array
+-   All options are displayed at all times.
+-   ```json
+    {
+    	"options": [
+    		{
+    			"name": "--help",
+    			"alias": ["-h"],
+    			"tip": "Show help."
+    		}
+    	]
+    }
+    ```
+
+### 4. `info`
+
+-   The type of value: object
+-   All values defined can be obtained elsewhere with the following syntax.
+-   ```json
+    // {{ $info.xxx }}
+    // {{ $json.xxx }} $json is the object of the entire json file.
+    {
+    	"root": [
+    		{
+    			"name": "test",
+    			"tip": "{{ $info.test_tip }}"
+    		},
+    		{
+    			"name": "abc",
+    			"tip": "{{ $json.info.abc_tip }}"
+    		}
+    	],
+    	"info": {
+    		"test_tip": "this is test content.",
+    		"abc_tip": "abcdefg"
+    	}
+    }
+    ```
+
+### 5. `config`
+
+-   The type of value: array
+-   Define some special configurations for completion.(e.g. `git`)
+-   ```json
+    "config": [
+        {
+        "name": "disable_hooks",
+        "value": 0,
+        "values": [
+            1,
+            0
+        ],
+        "tip": [
+            "Set whether to disable hooks. Default to 0.\n",
+            "Hooks in git are mainly used to parse commit information, branch information, etc., and then dynamically add them to some completions (such as reset,checkout,branch, etc.)\n",
+            "For example, enter <@Magenta>git reset<@Blue>, press <@Magenta>Space<@Blue> and <@Magenta>Tab<@Blue>, and you can get the resolved commit completions.\n",
+            "If you don't need it, you can disable it, which will improve the loading speed of the completion.\n",
+            "If you disable it, the <@Magenta>max_commit<@Blue> configuration will also be invalid."
+        ]
+        },
+        {
+        "name": "max_commit",
+        "value": 20,
+        "values": [
+            -1,
+            20
+        ],
+        "tip": [
+            "The maximum number that can be parsed for a project commit.\n",
+            "If it is <@Magenta>-1<@Blue>, all commits will be parsed.\n",
+            "If there are a large number of project commits, setting <@Magenta>-1<@Blue> will affect the loading speed of the completion."
+        ]
+        }
+    ]
+    ```
diff --git a/docs/en-US/contribute/index.md b/docs/en-US/contribute/index.md
@@ -0,0 +1,32 @@
+---
+title: About PR (Pull Request)
+prev:
+    text: About the structure of json file
+    link: '../completion/index.md'
+---
+
+# About PR (Pull Request)
+
+1. Prerequisite: You should read [About the structure of completion json file](../completion/index.md) first.
+2. You should fork [PSCompletions](https://github.com/abgox/PSCompletions), and clone to your machine.
+3. After Changing, you should commit and create the `PR`.
+
+## 1. Update the content of completion json file
+
+-   Patch some tips of the completion.(`tip` attributes)
+-   Add some missing commands for the completion.
+
+## 2. Add language
+
+1. In the `completions` directory, select the language you want to add.
+2. Add the language identifier to the language in the `config.json` file.
+3. Add a json file with the same name as the language identifier in the `language` directory.
+    - You can copy the original json file and rename it.
+4. Translate the contents of the `tip` attribute.
+
+## 3. Add a new completion
+
+1. Run it in the project root directory. `.\script\create.ps1`
+2. Follow the prompts.
+3. Modify the new completion.
+4. Add this completion to the value of the `list` property in `completions.json` in the project root directory.
diff --git a/docs/en-US/index.md b/docs/en-US/index.md
@@ -1,5 +1,25 @@
 ---
 layout: home
+hero:
+    name: PSCompletions
+    tagline: A completion manager for better and simpler use completions in PowerShell.
+    actions:
+        - theme: brand
+          text: About module command
+          link: en-US/command
+        - theme: alt
+          text: About the structure of json file
+          link: en-US/completion
+        - theme: alt
+          text: About PR (Pull Request)
+          link: en-US/contribute
+features:
+    - title: Multi-language
+      details: Switch between languages(zh-CN,en-US...) freely.
+    - title: Sort dynamically
+      details: Sort completion tab dynamically by frequency of use.
+    - title: New Completions menu
+      details: The module provides a more useful completion menu
+    - title: Base-in-json
+      details: Define completion data from json files.
 ---
-
-waiting...
diff --git a/docs/zh-CN/command/index.md b/docs/zh-CN/command/index.md
@@ -0,0 +1,11 @@
+---
+title: 模块命令
+next:
+    text: 关于贡献
+    link: '../contribute/index.md'
+---
+
+-   等待补充...
+    -   可以使用 `psc` 触发补全，通过补全提示信息了解模块命令
+    -   通过项目的 README 了解
+    -   输入 `psc` 后 按下 `enter`，将会打印一些模块信息