grep output *prdoc.toml

使用prdoc CLI

但是，您会发现安装并使用prddoc CLI会更方便，只需运行

prdoc generate 9999

编辑PRDoc文件后，您可以使用以下命令检查其是否符合架构

prdoc check check -n 1226

使用VSCode

参见架构章节，了解如何配置VSCode以识别和检查PRDoc文件。

YAML锚点

您可以使用以下示例中的YAML锚点。

# Schema: Parity PR Documentation Schema (prdoc)

title: Foobar

doc:
  - audience: Runtime User
    description: &desc |
      Sunt voluptate ad duis consequat ea in dolore non adipisicing incididunt
      ullamco enim qui enim.

  - audience: Validator
    description: *desc

migrations:
  db: []
  runtime: []

crates: []
host_functions: []

配置

使用配置文件使所有用户更容易，因为当他们使用prdoc时，可以省略一些必要的标志。

配置文件名称和位置

如果配置位于仓库根目录，并且名称为以下之一，则将找到配置

• prdoc.toml
• .prdoc.toml

或者，它也可以定义为名为PRDOC_CONFIG的环境变量，并包含相对于仓库根目录的配置路径。

内容

version = 1
schema = "tests/data/sample_schema.json"
output_dir = "/tmp/prdoc"
prdoc_folders = ["tests/data/all", "tests/data/some"]
template = "template.prdoc"

路径

为了使用户更容易使用，prdoc及其配置始终引用仓库的根目录。

这意味着您可以通过绝对路径或相对路径传递路径，但相对路径基于仓库的根目录，而不是当前工作目录。

这允许用户使用类似以下命令

prdoc check -n 1234
# instead of:
# prdoc check -n 1234 -d ../../folder/where/prdoc_files/are/stored

或者也可以

prdoc generate 1234
# instead of;
# prdoc generate 1234 -o ../../folder/where/prdoc_files/are/stored

架构

PR文档

PR文档的文档以扩展名为.prdoc的文件形式提供。这本质上是一个yaml文件，扩展名有助于使用正确的JSON架构来验证文件。

在VScode中，打开您的用户设置，并确保您有下面的部分

首先，您需要告诉VScode .prdoc文件是YAML文件

"files.associations": {
    "*.prdoc": "yaml",
},

然后，您需要指向正确的架构

 "yaml.schemas": {
    [...other schemas...]
    "/path/to/polkadot-sdk/prdoc/schema_user.json": "*polkadot-sdk*/**/*.prdoc",
    "/path/to/subxt/prdoc/schema_user.json": "*subxt*/**/*.prdoc"
  },

您需要重新启动/重新加载VSCode，以便新设置生效。

如果您最初使用其他扩展（如.txt）创建了文件，请确保在VSCode状态栏中将格式更改为YAML，然后应该选择正确的架构。

用法

prdoc is a utility to generate, check and load PRDoc files.

More at <https://github.com/paritytech/prdoc>

Usage: prdoc [OPTIONS] [COMMAND]

Commands:
  generate  Generate a new file. It will be saved by default unless you provide --dry-run. The command will fail if the target file already exists
  check     Check one or more prdoc files for validity
  scan      Scan a directory for prdoc files based on their name
  load      Load one or more prdoc
  help      Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>
          [env: PRDOC_CONFIG=]

  -d, --prdoc-folders <PRDOC_FOLDERS>
          [env: PRDOC_FOLDERS=]

  -v, --version
          Show the version

  -j, --json
          Output as json

  -h, --help
          Print help (see a summary with '-h')

生成

Generate a new file. It will be saved by default unless you provide --dry-run. The command will fail if the target file already exists

Usage: prdoc generate [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  Change number

Options:
      --dry-run                        Do not save the generated document to file with the proper naming, show the content instead
  -c, --config <CONFIG>                [env: PRDOC_CONFIG=]
  -o, --output-dir <OUTPUT_DIR>        Optional output directory. It not passed, the default `PRDOC_DIR` will be used under the root of the current project
  -d, --prdoc-folders <PRDOC_FOLDERS>  [env: PRDOC_FOLDERS=]
  -j, --json                           Output as json
  -h, --help                           Print help

检查

Check one or more prdoc files for validity

Usage: prdoc check [OPTIONS]

Options:
  -f, --file <FILE>                    Directly specify the file to be checked. It can be relative to the base directory
  -c, --config <CONFIG>                [env: PRDOC_CONFIG=]
  -n, --number <NUMBER>                number
  -d, --prdoc-folders <PRDOC_FOLDERS>  [env: PRDOC_FOLDERS=]
  -l, --list <LIST>                    Get the list of PR numbers from a file
  -s, --schema <SCHEMA>                Schema to be used. Passing this flag/ENV overrides the value from the config [env: PRDOC_SCHEMA=]
  -j, --json                           Output as json
  -h, --help                           Print help

扫描

Scan a directory for prdoc files based on their name

Usage: prdoc scan [OPTIONS]

Options:
  -a, --all                            Also return invalid files
  -c, --config <CONFIG>                [env: PRDOC_CONFIG=]
  -s, --sort                           Sort the output
  -d, --prdoc-folders <PRDOC_FOLDERS>  [env: PRDOC_FOLDERS=]
  -j, --json                           Output as json
  -h, --help                           Print help

加载

Load one or more prdoc

Usage: prdoc load [OPTIONS]

Options:
  -f, --file <FILE>                    file path
  -c, --config <CONFIG>                [env: PRDOC_CONFIG=]
  -n, --number <NUMBER>                One or more PR numbers. Depending on the host OS, the max length of a command may differ. If you run into issues, make sure to check the `--list` option instead
  -d, --prdoc-folders <PRDOC_FOLDERS>  [env: PRDOC_FOLDERS=]
  -l, --list <LIST>                    Get the list of PR numbers from a file
  -j, --json                           Output as json
  -h, --help                           Print help

容器

如果您不想安装Rust & Cargo并且已安装Podman或Docker，您可能更喜欢运行prdoc的容器化版本。本章将说明如何进行操作。

prdoc设计为在仓库级别工作，您需要将您的仓库作为/repo挂载到prdoc容器中。

podman run --rm -it -v $PWD:/repo paritytech/prdoc --help

    ENGINE=podman
    DOC_PATH="$PWD/tests/data/some"
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc --help
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc scan --all
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc check
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc load

默认情况下，容器镜像在/repo中工作，因此如果您将仓库挂载到那里，这会使事情变得简单。

运行

podman run --rm -it -v $PWD:/repo paritytech/prdoc --help

    ENGINE=podman
    DOC_PATH="$PWD/tests/data/some"
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc --help
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc scan --all
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc check
    $ENGINE run --rm -it -v $DOC_PATH:/repo paritytech/prdoc load

默认情况下，容器镜像在/repo中工作，因此如果您将仓库挂载到那里，这会使事情变得简单。

命令可能会变得相当长，因此你可能希望设置一个别名。

    alias prdoc='podman run --rm -it -v $PWD:/repo paritytech/prdoc'

设置这个别名后，你可以通过简单地调用 prdoc 命令来使用 prdoc。

    prdoc --version

这超出了本文档的范围，但请注意，你可以直接调用 prdoc check 并期望它在你的仓库中正常工作，前提是它包含有效的配置文件和模式。有关更多详细信息，请参阅???章节。

构建

你可以从 paritytech/prdoc 拉取容器镜像，或者自己构建。

    podman build -t prdoc .

许可证

Copyright 2021-2023 - Wilfried Kopp aka. Chevdor <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.