[docs] main.py: junit documentation elaboration (#19867)

Elaborate on the information given in --help and command_line.rst for
junit, to make it more correct and comprehensive.

I manually examined the generated results and found them satisfactory.

Note that this also puts --junit-format into misc group not import
group; the inclusion into imports group seems to have been a mistake in
#16388 although one could perhaps argue it is tangentially related to
imports in some way. But it does not influence import discovery, unlike
the other options. Putting it into import group also makes it display in
a completely different place, which is not as helpful as right next to
its related option.

Author: wyattscarpenter

docs/source/command_line.rst

@@ -1255,12 +1255,18 @@ Miscellaneous
    stub packages were found, they are installed and then another run
    is performed.
 
-.. option:: --junit-xml JUNIT_XML
+.. option:: --junit-xml JUNIT_XML_OUTPUT_FILE
 
     Causes mypy to generate a JUnit XML test result document with
     type checking results. This can make it easier to integrate mypy
     with continuous integration (CI) tools.
 
+.. option:: --junit-format {global,per_file}
+
+    If --junit-xml is set, specifies format.
+    global (default): single test with all errors;
+    per_file: one test entry per file with failures.
+
 .. option:: --find-occurrences CLASS.MEMBER
 
     This flag will make mypy print out all usages of a class member

docs/source/config_file.rst

@@ -1153,6 +1153,15 @@ These options may only be set in the global section (``[mypy]``).
     type checking results. This can make it easier to integrate mypy
     with continuous integration (CI) tools.
 
+.. confval:: junit_format
+
+    :type: string
+    :default: ``global``
+
+    If junit_xml is set, specifies format.
+    global (default): single test with all errors;
+    per_file: one test entry per file with failures.
+
 .. confval:: scripts_are_modules
 
     :type: boolean

mypy/main.py

@@ -1165,12 +1165,16 @@ def add_invertible_flag(
 
     misc_group = parser.add_argument_group(title="Miscellaneous")
     misc_group.add_argument("--quickstart-file", help=argparse.SUPPRESS)
-    misc_group.add_argument("--junit-xml", help="Write junit.xml to the given file")
-    imports_group.add_argument(
+    misc_group.add_argument(
+        "--junit-xml",
+        metavar="JUNIT_XML_OUTPUT_FILE",
+        help="Write a JUnit XML test result document with type checking results to the given file",
+    )
+    misc_group.add_argument(
         "--junit-format",
         choices=["global", "per_file"],
         default="global",
-        help="If --junit-xml is set, specifies format. global: single test with all errors; per_file: one test entry per file with failures",
+        help="If --junit-xml is set, specifies format. global (default): single test with all errors; per_file: one test entry per file with failures",
     )
     misc_group.add_argument(
         "--find-occurrences",