Skip to content

Commit 479fcc0

Browse files
waruqiwaruqi
committed
update docs
1 parent 7e93bf1 commit 479fcc0

10 files changed

Lines changed: 416 additions & 145 deletions

File tree

‎docs/config.ts‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -222,13 +222,45 @@ function guideSidebar(): DefaultTheme.SidebarItem[] {
222222
text: 'Official Addons',
223223
collapsed: true,
224224
items: [
225-
{ text: 'xmake-harness (xmake ai)', link: 'extensions/addons/official/xmake-harness' },
226-
{ text: 'esp32-devel', link: 'extensions/addons/official/esp32-devel' },
227-
{ text: 'avr-devel', link: 'extensions/addons/official/avr-devel' },
228-
{ text: 'serial-tools', link: 'extensions/addons/official/serial-tools' },
229-
{ text: 'yaml', link: 'extensions/addons/official/yaml' },
230-
{ text: 'Plugin Addons', link: 'extensions/addons/official/plugin-addons' },
231-
{ text: 'basic-templates', link: 'extensions/addons/official/basic-templates' },
225+
{
226+
text: 'Development Kits',
227+
collapsed: true,
228+
items: [
229+
{ text: 'esp32-devel', link: 'extensions/addons/official/esp32-devel' },
230+
{ text: 'avr-devel', link: 'extensions/addons/official/avr-devel' },
231+
]
232+
},
233+
{
234+
text: 'Tools',
235+
collapsed: true,
236+
items: [
237+
{ text: 'xmake-harness (xmake ai)', link: 'extensions/addons/official/xmake-harness' },
238+
{ text: 'serial-tools', link: 'extensions/addons/official/serial-tools' },
239+
]
240+
},
241+
{
242+
text: 'Modules',
243+
collapsed: true,
244+
items: [
245+
{ text: 'yaml', link: 'extensions/addons/official/yaml' },
246+
]
247+
},
248+
{
249+
text: 'Plugins',
250+
collapsed: true,
251+
items: [
252+
{ text: 'format-plugin', link: 'extensions/addons/official/format-plugin' },
253+
{ text: 'doxygen-plugin', link: 'extensions/addons/official/doxygen-plugin' },
254+
{ text: 'macro-plugin', link: 'extensions/addons/official/macro-plugin' },
255+
]
256+
},
257+
{
258+
text: 'Templates',
259+
collapsed: true,
260+
items: [
261+
{ text: 'basic-templates', link: 'extensions/addons/official/basic-templates' },
262+
]
263+
},
232264
]
233265
},
234266
]

‎docs/guide/extensions/addons/official/doxygen-plugin.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
outline: deep
3+
---
4+
5+
# doxygen-plugin
6+
7+
[doxygen-plugin](https://github.com/xmake-addons/doxygen-plugin) provides the `xmake doxygen`
8+
command, which generates the doxygen document of your project.
9+
10+
| Payload | What it provides |
11+
| --- | --- |
12+
| `plugins/doxygen` | the `xmake doxygen` command |
13+
14+
It generates a `doxyfile` from the project when there is none — the project name, version,
15+
source directory and output directory are filled in for you — and installs `doxygen` when it
16+
is missing.
17+
18+
::: tip NOTE
19+
This command used to be built into xmake and now ships as an addon. The builtin one still
20+
works but is deprecated: it prints a notice pointing at the addon, and an installed addon
21+
takes over the command.
22+
:::
23+
24+
## Installation
25+
26+
```sh
27+
$ xmake addon --install doxygen-plugin
28+
```
29+
30+
## Usage
31+
32+
```sh
33+
$ xmake doxygen # generate it, the source directory defaults to src
34+
$ xmake doxygen -o /tmp/docs mysrc # a custom output and source directory
35+
```
36+
37+
| Option | Default | Description |
38+
| --- | --- | --- |
39+
| `-o, --outputdir` | the build directory | the output directory of the document |
40+
| `srcdir` | `src` | the source code directory |
41+
42+
When it is done, it prints the path of the result page, i.e. `<outputdir>/html/index.html`.

‎docs/guide/extensions/addons/official/format-plugin.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
outline: deep
3+
---
4+
5+
# format-plugin
6+
7+
[format-plugin](https://github.com/xmake-addons/format-plugin) provides the `xmake format`
8+
command, which formats the sources of your project with clang-format.
9+
10+
| Payload | What it provides |
11+
| --- | --- |
12+
| `plugins/format` | the `xmake format` command |
13+
14+
It formats exactly the files your targets own, so generated code and third-party sources
15+
outside of the targets are never touched. `clang-format` is installed from xmake-repo when it
16+
is not on the host.
17+
18+
::: tip NOTE
19+
This command used to be built into xmake and now ships as an addon. The builtin one still
20+
works but is deprecated: it prints a notice pointing at the addon, and an installed addon
21+
takes over the command.
22+
:::
23+
24+
## Installation
25+
26+
```sh
27+
$ xmake addon --install format-plugin
28+
```
29+
30+
## Usage
31+
32+
```sh
33+
$ xmake format # all default targets
34+
$ xmake format target1 target2 # only the given targets
35+
$ xmake format -a # all targets
36+
$ xmake format -g test # a target group, `test_*` patterns work too
37+
$ xmake format --files='src/**.c|excluded.c'
38+
$ xmake format --create --style=Google # write a .clang-format
39+
```
40+
41+
| Option | Default | Description |
42+
| --- | --- | --- |
43+
| `-s, --style` | | the path of a `.clang-format` file, or a builtin style: `LLVM`, `Google`, `Chromium`, `Mozilla`, `WebKit` |
44+
| `--create` | | create a `.clang-format` from the given style |
45+
| `-n, --dry-run` | | do not change anything, just list the files which would be formatted |
46+
| `-e, --error` | | turn the formatting warnings into errors |
47+
| `-j, --jobs` | cpu cores | the number of parallel format jobs |
48+
| `-a, --all` | | format all targets |
49+
| `-g, --group` | | format the targets of the given group |
50+
| `-f, --files` | | the given source files, `**` and `|` exclusion are supported |
51+
52+
## Checking the format in the ci
53+
54+
`--dry-run` changes nothing, and with `--error` the command fails when a file does not match
55+
the style:
56+
57+
```sh
58+
$ xmake format --dry-run --error
59+
```

‎docs/guide/extensions/addons/official/macro-plugin.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
outline: deep
3+
---
4+
5+
# macro-plugin
6+
7+
[macro-plugin](https://github.com/xmake-addons/macro-plugin) provides the `xmake macro`
8+
command, which records a sequence of xmake commands as a macro and replays it later.
9+
10+
| Payload | What it provides |
11+
| --- | --- |
12+
| `plugins/macro` | the `xmake macro` command and the builtin `package` macro |
13+
14+
A macro is a lua script which replays xmake commands, and you record it instead of writing it.
15+
16+
::: tip NOTE
17+
This command used to be built into xmake and now ships as an addon. The builtin one still
18+
works but is deprecated: it prints a notice pointing at the addon, and an installed addon
19+
takes over the command.
20+
:::
21+
22+
## Installation
23+
24+
```sh
25+
$ xmake addon --install macro-plugin
26+
```
27+
28+
## Recording and replaying
29+
30+
```sh
31+
$ xmake macro --begin
32+
$ xmake config --plat=macosx
33+
$ xmake -r
34+
$ xmake macro --end test
35+
```
36+
37+
Then replay the whole sequence, `xmake macro` also has the short name `xmake m`:
38+
39+
```sh
40+
$ xmake macro test
41+
$ xmake m test
42+
```
43+
44+
Two macro names are special:
45+
46+
```sh
47+
$ xmake macro . # the anonymous macro, recorded without a name
48+
$ xmake macro .. # the last command
49+
```
50+
51+
## Managing macros
52+
53+
```sh
54+
$ xmake macro --list # list all macros
55+
$ xmake macro --show test # show the content of a macro
56+
$ xmake macro --delete test
57+
$ xmake macro --clear # clear all macros
58+
```
59+
60+
Macros can also be exported and imported, which is how you share them with your team:
61+
62+
```sh
63+
$ xmake macro --export=/xxx/macro.lua test
64+
$ xmake macro --export=/xxx/macrodir
65+
$ xmake macro --import=/xxx/macro.lua test
66+
$ xmake macro --import=/xxx/macrodir
67+
```
68+
69+
## The builtin package macro
70+
71+
It comes with a `package` macro, which packages the project for several architectures at once:
72+
73+
```sh
74+
$ xmake macro package -p iphoneos -f "-m debug"
75+
```

‎docs/guide/extensions/addons/official/plugin-addons.md‎

Lines changed: 0 additions & 69 deletions
This file was deleted.

‎docs/zh/config.ts‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -303,13 +303,45 @@ function guideSidebar(): DefaultTheme.SidebarItem[] {
303303
text: '官方 Addons',
304304
collapsed: true,
305305
items: [
306-
{ text: 'xmake-harness (xmake ai)', link: 'extensions/addons/official/xmake-harness' },
307-
{ text: 'esp32-devel', link: 'extensions/addons/official/esp32-devel' },
308-
{ text: 'avr-devel', link: 'extensions/addons/official/avr-devel' },
309-
{ text: 'serial-tools', link: 'extensions/addons/official/serial-tools' },
310-
{ text: 'yaml', link: 'extensions/addons/official/yaml' },
311-
{ text: '插件类 Addon', link: 'extensions/addons/official/plugin-addons' },
312-
{ text: 'basic-templates', link: 'extensions/addons/official/basic-templates' },
306+
{
307+
text: '开发套件类',
308+
collapsed: true,
309+
items: [
310+
{ text: 'esp32-devel', link: 'extensions/addons/official/esp32-devel' },
311+
{ text: 'avr-devel', link: 'extensions/addons/official/avr-devel' },
312+
]
313+
},
314+
{
315+
text: '工具类',
316+
collapsed: true,
317+
items: [
318+
{ text: 'xmake-harness (xmake ai)', link: 'extensions/addons/official/xmake-harness' },
319+
{ text: 'serial-tools', link: 'extensions/addons/official/serial-tools' },
320+
]
321+
},
322+
{
323+
text: '扩展模块类',
324+
collapsed: true,
325+
items: [
326+
{ text: 'yaml', link: 'extensions/addons/official/yaml' },
327+
]
328+
},
329+
{
330+
text: '插件类',
331+
collapsed: true,
332+
items: [
333+
{ text: 'format-plugin', link: 'extensions/addons/official/format-plugin' },
334+
{ text: 'doxygen-plugin', link: 'extensions/addons/official/doxygen-plugin' },
335+
{ text: 'macro-plugin', link: 'extensions/addons/official/macro-plugin' },
336+
]
337+
},
338+
{
339+
text: '模板类',
340+
collapsed: true,
341+
items: [
342+
{ text: 'basic-templates', link: 'extensions/addons/official/basic-templates' },
343+
]
344+
},
313345
]
314346
},
315347
]

‎docs/zh/guide/extensions/addons/official/doxygen-plugin.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
outline: deep
3+
---
4+
5+
# doxygen-plugin
6+
7+
[doxygen-plugin](https://github.com/xmake-addons/doxygen-plugin) 提供 `xmake doxygen` 命令，为工程生成 doxygen 文档。
8+
9+
| 目录 | 提供什么 |
10+
| --- | --- |
11+
| `plugins/doxygen` | `xmake doxygen` 命令 |
12+
13+
工程里没有 `doxyfile` 时，它会自动生成一份，工程名、版本号、源码目录和输出目录都会自动填好。主机上没有 `doxygen` 时，也会自动安装一个。
14+
15+
::: tip 注意
16+
这个命令原本内置在 xmake 中，现在改为 addon 分发。内置版本仍然可用，但已经废弃，执行时会提示改用 addon，装了 addon 之后命令由 addon 接管。
17+
:::
18+
19+
## 安装
20+
21+
```sh
22+
$ xmake addon --install doxygen-plugin
23+
```
24+
25+
## 使用
26+
27+
```sh
28+
$ xmake doxygen # 生成文档，源码目录默认 src
29+
$ xmake doxygen -o /tmp/docs mysrc # 指定输出目录和源码目录
30+
```
31+
32+
| 参数 | 默认值 | 说明 |
33+
| --- | --- | --- |
34+
| `-o, --outputdir` | 工程的构建目录 | 文档的输出目录 |
35+
| `srcdir` | `src` | 源码目录 |
36+
37+
生成完成后会打印结果页面的路径，即 `<outputdir>/html/index.html`。

0 commit comments

Comments
 (0)