PRDoc

prdoc is a tool helping with .prdoc files. .prdoc files are YAML files following a defined schema and helping with code change documentation. While platform like Github allow a simple description for a Pull Request (PR), this is limited to a title, description and some labels. The description itself is often used to describe the change but not document it.

The schema can be found here: schema_user.json.

Install

cargo install prdoc

Alternatively, you may use a the container image:

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

The container image is working by default in /doc so it makes it simpler if you mount your doc there as shown above.

Features

• provide the prdoc user schema - generate new documents - scan for prdoc in a folder - check prdoc files - load/aggregate prdoc files

Schemas

PR Doc

The documentation for PRs comes as a file with the extension .prdoc. This is essentially a yaml file and the extension helps using the right JSON schema to validate the file.

In VScode, open your user settings and ensure you have the following section:

"yaml.schemas":  {
    "/path/of/schema/pr_doc.json": "*.prdoc"
},

Should initially have created the file with another extension such as .txt, make sure to change the format to YAML and the right schema should then be picked up.

Usage

Definition of the cli flags and subcommands

Usage: prdoc [OPTIONS] [COMMAND]

Commands:
  generate  Generate a new file. It will be printed to stdout by default unless you provide the `--save` flag
  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
  schema    Retrieve the JSON schema that is used internally
  help      Print this message or the help of the given subcommand(s)

Options:
  -v, --version  Show the version
  -j, --json     Output as json
  -h, --help     Print help

Schema

Retrieve the JSON schema that is used internally

Usage: prdoc schema [OPTIONS]

Options:
  -j, --json  Output as json
  -h, --help  Print help

Generate

Generate a new file. It will be printed to stdout by default unless you provide the `--save` flag

Usage: prdoc generate [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  Change number

Options:
  -t, --title <TITLE>            Change title
  -s, --save                     Save the generated document to file with the proper naming
  -o, --output-dir <OUTPUT_DIR>  Output directory [default: .]
  -j, --json                     Output as json
  -h, --help                     Print help

Scan

Scan a directory for prdoc files based on their name

Usage: prdoc scan [OPTIONS] [DIRECTORY]

Arguments:
  [DIRECTORY]  directory path [default: .]

Options:
  -a, --all   Also return invalid files
  -j, --json  Output as json
  -h, --help  Print help

Check

Check one or MORE `prdoc` files for validity

Usage: prdoc check [OPTIONS]

Options:
  -d, --directory <DIRECTORY>  Base directory for the files [default: .]
  -f, --file <FILE>            Directly specify the file to be checked. It can be relative to the base directory
  -n, --number <NUMBER>        number
  -l, --list <LIST>            Get the list of PR numbers from a file
  -j, --json                   Output as json
  -h, --help                   Print help

Load

Load one or more prdoc

Usage: prdoc load [OPTIONS]

Options:
  -d, --directory <DIRECTORY>  directory path [default: .]
  -f, --file <FILE>            file path
  -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
  -l, --list <LIST>            Get the list of PR numbers from a file
  -j, --json                   Output as json
  -h, --help                   Print help

Docker

If you prefer not having to install Rust & Cargo and have Docker installed, you may prefer to run a containerized version of prdoc. The next chapters explain how to proceed.

Run

Docker commands can end up quite lengthy so you may like to set an alias:

[subs="attributes+"] ---- alias prdoc='docker run --rm -it prdoc'

After setting this alias, you may use {cli} by simply invoking the {cli} command:

[subs="attributes+"] ----
    {prj} --version

If you prefer a shorter a command, you may set an alias for rl instead of prdoc.

This is out of the scope of this documentation but note that you cannot just invoke prdoc check and expect it to work on your local specs.yaml. For that to work, you need to mount your specs.yaml into the container. That looks like this:

[subs="attributes+"] ---- docker run --rm -it -v $PWD/specs.yaml:/usr/local/bin/specs.yaml prdoc list

=== Build

You can pull the docker image from `chevdor`/{cli} or build you own:

[subs="attributes+"] ----
    docker build -t {prj} .

License

---- include::LICENSE[] ----