improve prdoc generation (#5931)

Related to
#5924 (comment)

improve prdoc arguments validation & help:
- convert audiences options to snake_case. Fixes
#5927
  - support more than one audiences
  - define allowed bump options
- infer --pr from the actual PR (now it's optional, can still be
overwritten)


![image](https://github.com/user-attachments/assets/24e18fe2-2f67-4ce0-90e4-34f6c2f860c9)

Test evidence:
paritytech-stg@6dd274e

.github/scripts/cmd/cmd.py

@@ -77,7 +77,7 @@
 spec.loader.exec_module(generate_prdoc)
 
 parser_prdoc = subparsers.add_parser('prdoc', help='Generates PR documentation')
-generate_prdoc.setup_parser(parser_prdoc)
+generate_prdoc.setup_parser(parser_prdoc, pr_required=False)
 
 def main():
     global args, unknown, runtimesMatrix

.github/scripts/generate-prdoc.py

@@ -7,7 +7,7 @@
 This will delete any prdoc that already exists for the PR if `--force` is passed.
 
 Usage:
-	python generate-prdoc.py --pr 1234 --audience "TODO" --bump "TODO"
+	python generate-prdoc.py --pr 1234 --audience node_dev --bump patch
 """
 
 import argparse
@@ -110,27 +110,33 @@ def yaml_multiline_string_presenter(dumper, data):
 	yaml.add_representer(str, yaml_multiline_string_presenter)
 
 # parse_args is also used by cmd/cmd.py
-def setup_parser(parser=None):
+# if pr_required is False, then --pr is optional, as it can be derived from the PR comment body
+def setup_parser(parser=None, pr_required=True):
+	allowed_audiences = ["runtime_dev", "runtime_user", "node_dev", "node_operator"]
 	if parser is None:
 		parser = argparse.ArgumentParser()
-	parser.add_argument("--pr", type=int, required=True, help="The PR number to generate the PrDoc for."	)
-	parser.add_argument("--audience", type=str, default="TODO", help="The audience of whom the changes may concern.")
-	parser.add_argument("--bump", type=str, default="TODO", help="A default bump level for all crates.")
-	parser.add_argument("--force", type=str, help="Whether to overwrite any existing PrDoc.")
-
+	parser.add_argument("--pr", type=int, required=pr_required, help="The PR number to generate the PrDoc for.")
+	parser.add_argument("--audience", type=str, nargs='*', choices=allowed_audiences, default=["todo"], help="The audience of whom the changes may concern. Example: --audience runtime_dev node_dev")
+	parser.add_argument("--bump", type=str, default="major", choices=["patch", "minor", "major", "silent", "ignore", "no_change"], help="A default bump level for all crates. Example: --bump patch")
+	parser.add_argument("--force", action="store_true", help="Whether to overwrite any existing PrDoc.")
 	return parser
 
+def snake_to_title(s):
+    return ' '.join(word.capitalize() for word in s.split('_'))
+
 def main(args):
-	force = True if (args.force or "false").lower() == "true" else False
-	print(f"Args: {args}, force: {force}")
+	print(f"Args: {args}, force: {args.force}")
 	setup_yaml()
 	try:
-		from_pr_number(args.pr, args.audience, args.bump, force)
+		# Convert snake_case audience arguments to title case
+		mapped_audiences = [snake_to_title(a) for a in args.audience]
+		from_pr_number(args.pr, mapped_audiences, args.bump, args.force)
 		return 0
 	except Exception as e:
 		print(f"Error generating prdoc: {e}")
 		return 1
 
 if __name__ == "__main__":
-	args = setup_parser().parse_args()
+	parser = setup_parser()
+	args = parser.parse_args()
 	main(args)

.github/workflows/cmd.yml

@@ -152,15 +152,15 @@ jobs:
         id: get-pr-comment
         with:
           text: ${{ github.event.comment.body }}
-          regex: '^(\/cmd )([-\/\s\w.=:]+)$' # see explanation in docs/contributor/commands-readme.md#examples
+          regex: "^(\\/cmd )([-\\/\\s\\w.=:]+)$" # see explanation in docs/contributor/commands-readme.md#examples
 
       - name: Save output of help
         id: help
         env:
           CMD: ${{ steps.get-pr-comment.outputs.group2 }} # to avoid "" around the command
         run: |
-          echo 'help<<EOF' >> $GITHUB_OUTPUT
           python3 -m pip install -r .github/scripts/generate-prdoc.requirements.txt
+          echo 'help<<EOF' >> $GITHUB_OUTPUT
           python3 .github/scripts/cmd/cmd.py $CMD >> $GITHUB_OUTPUT
           echo 'EOF' >> $GITHUB_OUTPUT
 
@@ -291,7 +291,18 @@ jobs:
         id: get-pr-comment
         with:
           text: ${{ github.event.comment.body }}
-          regex: '^(\/cmd )([-\/\s\w.=:]+)$' # see explanation in docs/contributor/commands-readme.md#examples
+          regex: "^(\\/cmd )([-\\/\\s\\w.=:]+)$" # see explanation in docs/contributor/commands-readme.md#examples
+
+      # In order to run prdoc without specifying the PR number, we need to add the PR number as an argument automatically
+      - name: Prepare PR Number argument
+        id: pr-arg
+        run: |
+          CMD="${{ steps.get-pr-comment.outputs.group2 }}"
+          if echo "$CMD" | grep -q "prdoc" && ! echo "$CMD" | grep -qE "\-\-pr[[:space:]=][0-9]+"; then
+            echo "arg=--pr ${{ github.event.issue.number }}" >> $GITHUB_OUTPUT
+          else
+            echo "arg=" >> $GITHUB_OUTPUT
+          fi
 
       - name: Build workflow link
         if: ${{ !contains(github.event.comment.body, '--quiet') }}
@@ -314,7 +325,8 @@ jobs:
           echo "run_url=$runLink" >> $GITHUB_OUTPUT
 
       - name: Comment PR (Start)
-        if: ${{ !contains(github.event.comment.body, '--quiet') }}
+        # No need to comment on prdoc start or if --quiet
+        if: ${{ !contains(github.event.comment.body, '--quiet') && !contains(github.event.comment.body, 'prdoc') }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -344,14 +356,15 @@ jobs:
         id: cmd
         env:
           CMD: ${{ steps.get-pr-comment.outputs.group2 }} # to avoid "" around the command
+          PR_ARG: ${{ steps.pr-arg.outputs.arg }}
         run: |
-          echo "Running command: '$CMD' on '${{ needs.set-image.outputs.RUNNER }}' runner, container: '${{ needs.set-image.outputs.IMAGE }}'"
+          echo "Running command: '$CMD $PR_ARG' on '${{ needs.set-image.outputs.RUNNER }}' runner, container: '${{ needs.set-image.outputs.IMAGE }}'"
           echo "RUST_NIGHTLY_VERSION: $RUST_NIGHTLY_VERSION"
           # Fixes "detected dubious ownership" error in the ci
           git config --global --add safe.directory '*'
           git remote -v
           python3 -m pip install -r .github/scripts/generate-prdoc.requirements.txt
-          python3 .github/scripts/cmd/cmd.py $CMD
+          python3 .github/scripts/cmd/cmd.py $CMD $PR_ARG
           git status
           git diff
 
@@ -395,7 +408,8 @@ jobs:
           } >> $GITHUB_OUTPUT
 
       - name: Comment PR (End)
-        if: ${{ !failure() && !contains(github.event.comment.body, '--quiet') }}
+        # No need to comment on prdoc success or --quiet
+        if: ${{ !failure() && !contains(github.event.comment.body, '--quiet') && !contains(github.event.comment.body, 'prdoc') }}
         uses: actions/github-script@v7
         env:
           SUBWEIGHT: "${{ steps.subweight.outputs.result }}"

.github/workflows/command-prdoc.yml

@@ -14,7 +14,7 @@ on:
         required: true
         options:
           - "TODO"
-          - "no change"
+          - "no_change"
           - "patch"
           - "minor"
           - "major"
@@ -25,18 +25,15 @@ on:
         required: true
         options:
           - "TODO"
-          - "Runtime Dev"
-          - "Runtime User"
-          - "Node Dev"
-          - "Node Operator"
+          - "runtime_dev"
+          - "runtime_user"
+          - "node_dev"
+          - "node_operator"
       overwrite:
-        type: choice
+        type: boolean
         description: Overwrite existing PrDoc
-        default: "true"
+        default: true
         required: true
-        options:
-          - "true"
-          - "false"
 
 concurrency:
   group: command-prdoc
@@ -81,4 +78,4 @@ jobs:
         with:
           commit_message: Add PrDoc (auto generated)
           branch: ${{ steps.gh.outputs.branch }}
-          file_pattern: 'prdoc/*.prdoc'
+          file_pattern: "prdoc/*.prdoc"

docs/contributor/commands-readme.md

@@ -44,4 +44,5 @@ the default branch.
 The regex in cmd.yml is: `^(\/cmd )([-\/\s\w.=:]+)$` accepts only alphanumeric, space, "-", "/", "=", ":", "." chars.
 
 `/cmd bench --runtime bridge-hub-westend --pallet=pallet_name`
+`/cmd prdoc --audience runtime_dev runtime_user --bump patch --force`
 `/cmd update-ui --image=docker.io/paritytech/ci-unified:bullseye-1.77.0-2024-04-10-v202407161507 --clean`