PRDoc

prdoc 是一个工具，旨在帮助生成、检查和加载 .prdoc 文件。 .prdoc 文件是符合定义的JSON模式的YAML文件，有助于代码更改文档。

虽然像Github这样的平台允许为拉取请求（PR）提供一个简单的描述，但这仅限于标题、描述和一些标签。

PR本身的描述通常用来描述更改，但不是以结构化的方式记录。一个示例模式可以在这里找到： prdoc_schema_user.json，但每个仓库都可以定义自己的JSON模式。

特性

• generate命令：创建新的PRDoc文件

• scan命令：快速扫描文件夹中的PRDOc文件

• check命令：检查一个或多个PRDOc文件

• load命令：加载一个或多个PRDoc文件

安装

cargo install prdoc

或者，如果您不想在系统上安装任何东西，可以使用容器镜像。有关容器更多详情，请参阅容器部分。

理念

配置、命令行标志和环境变量

为了在一个仓库中提供简单且一致的行为，prdoc 将查找本地配置文件。配置文件是一个名为 .prdoc.toml 或 prdoc.toml 的YAML文件，位于仓库的根目录。

配置文件也可以通过ENV（PRDOC_CONFIG）或命令行标志（-c|--config）传递。ENV和命令行标志具有高于本地配置文件的优先级。

易于使用

虽然大多数命令都支持选项，但它们被设计得易于使用，并且在存在配置文件或 .env 文件时，用户输入量最小。

编写 PRDoc

无工具

编写新的 PRDoc 不需要工具，只需一个文本编辑器即可。您可以直接从您的仓库中复制模板。该模板在 这里 定义

grep template *prdoc.toml

然后，您需要将文件保存为 pr_NNNN.prdoc（其中 NNN 是 PR 编号）在仓库的 prdoc 文件夹中。此文件夹也在配置中定义（默认为 ./prdoc）

grep output *prdoc.toml

使用 prdoc 命令行界面

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

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 的 ENV，并包含相对于仓库根目录的配置路径。

内容

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

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

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

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

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.