# PRDoc
<figure>
<img src="https://github.com/chevdor/prdoc/actions/workflows/quick-check.yml/badge.svg?branch=master" alt="badge" />
</figure>
`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](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\[\] ----