{"id":17208669,"url":"https://github.com/chevdor/prdoc","last_synced_at":"2025-03-25T11:23:14.314Z","repository":{"id":216311715,"uuid":"738615249","full_name":"chevdor/prdoc","owner":"chevdor","description":"The prdoc cli tool allows better managing the documentation of your changed and the doc remains part of the git repo. It relies on YAML files following a defined schema and helping with code change documentation.","archived":false,"fork":false,"pushed_at":"2024-02-20T11:12:15.000Z","size":6293,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T01:51:53.614Z","etag":null,"topics":["cli","documentation","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chevdor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-03T16:30:25.000Z","updated_at":"2024-08-30T12:49:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"c42cb731-4766-4e9c-b263-d1dac3d631be","html_url":"https://github.com/chevdor/prdoc","commit_stats":null,"previous_names":["chevdor/prdoc"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fprdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fprdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fprdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chevdor%2Fprdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chevdor","download_url":"https://codeload.github.com/chevdor/prdoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245450432,"owners_count":20617350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","documentation","rust"],"created_at":"2024-10-15T02:49:32.838Z","updated_at":"2025-03-25T11:23:14.286Z","avatar_url":"https://github.com/chevdor.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PRDoc\n\n\u003cfigure\u003e\n\u003cimg src=\"https://github.com/chevdor/prdoc/actions/workflows/quick-check.yml/badge.svg?branch=master\" alt=\"badge\" /\u003e\n\u003c/figure\u003e\n\n`prdoc` is a tool designed to help generating, checking and loading `.prdoc` files.\n`.prdoc` files are YAML files adhering to defined JSON schema and helping with\ncode change documentation.\n\nWhile platform like Github allow a simple description for a Pull Request (PR), this is\nlimited to a title, description and some labels.\n\nThe description of a PR itself is often used to describe the change but not\ndocument it in a structured fashion.\nA sample schema can be found here: [prdoc\\_schema\\_user.json](prdoc_schema_user.json) but each repository is free to\ndefine its own JSON Schema.\n\n## Features\n\n-   [generate command](#_install) to create new PRDoc files\n\n-   [scan command](#_scan): to quickly scan for PRDOc files in a folder\n\n-   [check command](#_check): to check one or more PRDOc files\n\n-   [load command](#_load): to load one or more PRDoc files\n\n## Install\n\n    cargo install prdoc\n\nAlternatively, you may use a the container image if you prefer not installing anything on your system. See the\n[Containers](#_containers) section for more details on containers.\n\n## Philosophy\n\n### Configuration, cli flags and environment variables\n\nIn order to provide a simple and uniform behavior in a repo, `prdoc` will search for a local configuration file.\nThe configuration file is a YAML file named `.prdoc.toml` or `prdoc.toml` and located in the root of the repo.\n\nThe configuration file can alternatively be passed via ENV (`PRDOC_CONFIG`) or cli flag (`-c`|`--config`).\nENV and cli flags have precedence over the local configuration file.\n\n### Simple to use\n\nWhile most commands supports options, they are designed to be simple to use and require a minimal amount of user input\nwhen either a config or an `.env` file is present.\n\n## Authoring a PRDoc\n\n### Without tooling\n\nNo tooling but a text editor is required to author a new PRDoc. You may simply copy the template from your repo.\nThe template is defined in the [???](#config):\n\n    grep template *prdoc.toml\n\nYou then need to save the file as `pr_NNNN.prdoc` (where `NNN` is the PR number) in the repo’s prdoc folder.\nThis folder is also defined in the config (`./prdoc` is the default\\`):\n\n    grep output *prdoc.toml\n\n### Using the `prdoc` cli\n\nYou will however find it more convenient to [install](https://github.com/chevdor/prdoc#install) and use the `prddoc`\ncli and just run:\n\n    prdoc generate 9999\n\nAfter editing the PRDoc file, you may check whether is adheres to the schema using:\n\n    prdoc check check -n 1226\n\n### Using VSCode\n\nSee the [Schemas](#_schemas) chapter to learn how to configure VSCode to recognize and check PRDoc files.\n\n### YAML Anchors\n\nYou may use YAML anchors as demonnstrated below.\n\n    # Schema: Parity PR Documentation Schema (prdoc)\n\n    title: Foobar\n\n    doc:\n      - audience: Runtime User\n        description: \u0026desc |\n          Sunt voluptate ad duis consequat ea in dolore non adipisicing incididunt\n          ullamco enim qui enim.\n\n      - audience: Validator\n        description: *desc\n\n    migrations:\n      db: []\n      runtime: []\n\n    crates: []\n    host_functions: []\n\n## Config\n\nUsing a configuration file makes it easier for all users as they will be able to omit some of the required flags when\nusing the `prdoc`.\n\n### Config file name and location\n\nThe config will be found if located at the root of the repo and named either:\n- `prdoc.toml`\n- `.prdoc.toml`\n\nAlternatively, it can be defined as an ENV named `PRDOC_CONFIG` and contain the path of the config, relative to the\nrepository’s root.\n\n### Content\n\n    version = 1\n    schema = \"tests/data/sample_schema.json\"\n    output_dir = \"/tmp/prdoc\"\n    prdoc_folders = [\"tests/data/all\", \"tests/data/some\"]\n    template = \"template.prdoc\"\n\n## Paths\n\nIn order to make it easier to use, `prdoc` and its configuration always refer to the **root of the repository**.\n\nIt means you can pass either absolute paths or relative ones but relatives ones are based on the root of the repo and\n**not** the current working directory.\n\nThis allows users to use commands such as:\n\n    prdoc check -n 1234\n    # instead of:\n    # prdoc check -n 1234 -d ../../folder/where/prdoc_files/are/stored\n\nOr also:\n\n    prdoc generate 1234\n    # instead of;\n    # prdoc generate 1234 -o ../../folder/where/prdoc_files/are/stored\n\n## Schemas\n\n### PR Doc\n\nThe documentation for PRs comes as a file with the extension `.prdoc`.\nThis is essentially a `yaml` file and the extension helps using the right JSON schema to validate the file.\n\nIn VScode, open your user settings and ensure you have the following section:\n\nYou first need to tell VScode that .prdoc files are YAML files:\n\n    \"files.associations\": {\n        \"*.prdoc\": \"yaml\",\n    },\n\nYou then need to point to the right schemas:\n\n     \"yaml.schemas\": {\n        [...other schemas...]\n        \"/path/to/\u003cyour_repo\u003e\u003e/prdoc/schema_user.json\": \"*\u003cyour_repo\u003e\u003e*/**/*.prdoc\",\n        \"/path/to/subxt/prdoc/schema_user.json\": \"*subxt*/**/*.prdoc\"\n      },\n\nYou need to restart/reload VSCode after those changes for the new settings to be picked up.\n\nShould you initially have created the file with another extension such as `.txt`, make sure to change the format to\n`YAML` in the VSCode status bar and the right schema should then be picked up.\n\n## Usage\n\n    prdoc is a utility to generate, check and load PRDoc files.\n\n    More at \u003chttps://github.com/chevdor/prdoc\u003e\n\n    Usage: prdoc [OPTIONS] [COMMAND]\n\n    Commands:\n      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\n      check     Check one or more prdoc files for validity\n      scan      Scan a directory for prdoc files based on their name\n      load      Load one or more prdoc\n      help      Print this message or the help of the given subcommand(s)\n\n    Options:\n      -c, --config \u003cCONFIG\u003e\n              [env: PRDOC_CONFIG=.prdoc-sdk.toml]\n\n      -d, --prdoc-folders \u003cPRDOC_FOLDERS\u003e\n              [env: PRDOC_FOLDERS=]\n\n      -v, --version\n              Show the version\n\n      -j, --json\n              Output as json\n\n      -h, --help\n              Print help (see a summary with '-h')\n\n### generate\n\n    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\n\n    Usage: prdoc generate [OPTIONS] \u003cNUMBER\u003e\n\n    Arguments:\n      \u003cNUMBER\u003e  Change number\n\n    Options:\n          --dry-run                        Do not save the generated document to file with the proper naming, show the content instead\n      -c, --config \u003cCONFIG\u003e                [env: PRDOC_CONFIG=.prdoc-sdk.toml]\n      -o, --output-dir \u003cOUTPUT_DIR\u003e        Optional output directory. It not passed, the default `PRDOC_DIR` will be used under the root of the current project\n      -d, --prdoc-folders \u003cPRDOC_FOLDERS\u003e  [env: PRDOC_FOLDERS=]\n      -j, --json                           Output as json\n      -h, --help                           Print help\n\n### check\n\n    Check one or more prdoc files for validity\n\n    Usage: prdoc check [OPTIONS]\n\n    Options:\n      -f, --file \u003cFILE\u003e                    Directly specify the file to be checked. It can be relative to the base directory\n      -c, --config \u003cCONFIG\u003e                [env: PRDOC_CONFIG=.prdoc-sdk.toml]\n      -n, --number \u003cNUMBER\u003e                number\n      -d, --prdoc-folders \u003cPRDOC_FOLDERS\u003e  [env: PRDOC_FOLDERS=]\n      -l, --list \u003cLIST\u003e                    Get the list of PR numbers from a file\n      -s, --schema \u003cSCHEMA\u003e                Schema to be used. Passing this flag/ENV overrides the value from the config [env: PRDOC_SCHEMA=]\n      -j, --json                           Output as json\n      -h, --help                           Print help\n\n### scan\n\n    Scan a directory for prdoc files based on their name\n\n    Usage: prdoc scan [OPTIONS]\n\n    Options:\n      -a, --all                            Also return invalid files\n      -c, --config \u003cCONFIG\u003e                [env: PRDOC_CONFIG=.prdoc-sdk.toml]\n      -s, --sort                           Sort the output\n      -d, --prdoc-folders \u003cPRDOC_FOLDERS\u003e  [env: PRDOC_FOLDERS=]\n      -j, --json                           Output as json\n      -h, --help                           Print help\n\n### load\n\n    Load one or more prdoc\n\n    Usage: prdoc load [OPTIONS]\n\n    Options:\n      -f, --file \u003cFILE\u003e                    file path\n      -c, --config \u003cCONFIG\u003e                [env: PRDOC_CONFIG=.prdoc-sdk.toml]\n      -n, --number \u003cNUMBER\u003e                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\n      -d, --prdoc-folders \u003cPRDOC_FOLDERS\u003e  [env: PRDOC_FOLDERS=]\n      -l, --list \u003cLIST\u003e                    Get the list of PR numbers from a file\n      -s, --schema \u003cSCHEMA\u003e                Schema to be used. Passing this flag/ENV overrides the value from the config [env: PRDOC_SCHEMA=]\n      -j, --json                           Output as json\n      -h, --help                           Print help\n\n## Containers\n\nIf you prefer not having to install Rust \u0026 Cargo and have Podman or Docker installed, you may prefer to run a containerized\nversion of `prdoc`. This chapter explains how to proceed.\n\nprdoc is designed to work at the repository level and you need to mount your repo as `/repo` into the prdoc container.\n\n    podman run --rm -it -v $PWD:/repo chevdor/prdoc --help\n\n        ENGINE=podman\n        DOC_PATH=\"$PWD/tests/data/some\"\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc --help\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc scan --all\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc check\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc load\n\nThe container image is working by default in `/repo` so it makes it simpler if you mount your repo there as shown\nabove.\n\n### Run\n\n    podman run --rm -it -v $PWD:/repo chevdor/prdoc --help\n\n        ENGINE=podman\n        DOC_PATH=\"$PWD/tests/data/some\"\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc --help\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc scan --all\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc check\n        $ENGINE run --rm -it -v $DOC_PATH:/repo chevdor/prdoc load\n\nThe container image is working by default in `/repo` so it makes it simpler if you mount your repo there as shown\nabove.\n\nCommands can end up quite lengthy so you may like to set an alias:\n\n        alias prdoc='podman run --rm -it -v $PWD:/repo chevdor/prdoc'\n\nAfter setting this alias, you may use `prdoc` by simply invoking the `prdoc` command:\n\n        prdoc --version\n\nThis is out of the scope of this documentation but note that you can just invoke `prdoc check` and expect it to work in\nyour repo as long as it contains a valid configuration file and schema. Check out the [???](#Configuration) chapter for more\ndetails.\n\n### Build\n\nYou can pull the container image from `chevdor`/`prdoc` or build you own:\n\n        podman build -t prdoc .\n\n## License\n\n    Copyright 2021-2023 - Wilfried Kopp aka. Chevdor \u003cchevdor@gmail.com\u003e\n\n    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated\n    documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the\n    rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit\n    persons to whom the Software is furnished to do so, subject to the following conditions:\n\n    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the\n    Software.\n\n    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE\n    WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\n    COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR\n    OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchevdor%2Fprdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchevdor%2Fprdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchevdor%2Fprdoc/lists"}