Repository: pyinstaller/pyinstaller

Issue:
Docs for --debug is not what occurs
Under the ["How to Generate"](https://pyinstaller.readthedocs.io/en/stable/usage.html#how-to-generate) header in the usage, debug arguments have been updated to reflect the new changes. First of all "–debug" needs to be "--debug" but the bigger issue is that you will be provided an error when passing -d/--debug on their own even though the usage states:

> all: All three of the below options; this is the default choice, unless one of the choices below is specified.

An example of this:
```
pyinstaller --debug my_script.py
```
this will produce the following error:
```
pyinstaller: error: argument -d/--debug: invalid choice: 'my_script.py' (choose from 'all', 'imports', 'bootloader', 'noarchive')
```
Passing one of {all,imports,bootloader,noarchive} solves this, for example:
```
pyinstaller --debug all my_script.py
```

I am using Windows 10, Python 3.6.6/3.7 and this is tested with PyInstaller-3.5.dev0+634a0c8ba/3.4.



Discussion:
Good point. There are two problems I can see:

1. The formatting for the `--debug` option is incorrect. This is because docutils doesn't understand `argparse` results for this more complex scenario. We could use an automatic search and replace to fix this up before handing it to docutils/Sphinx. @htgoebel, what do you think -- I already see some fixup at https://github.com/pyinstaller/pyinstaller/blob/develop/doc/help2rst.py#L73. Adding to this would be (I think) fairly easy.
2. The docs are incorrect. I'll change the description of the `all` option to be: "all: All three of the below options." In addition, 



Resolving patch:
diff --git a/PyInstaller/building/makespec.py b/PyInstaller/building/makespec.py
--- a/PyInstaller/building/makespec.py
+++ b/PyInstaller/building/makespec.py
@@ -172,11 +172,8 @@ def __add_options(parser):
                    # If this option is not specified, then its default value is
                    # an empty list (no debug options selected).
                    default=[],
-                   # Allow the user to specify any number of arguments.
-                   nargs='?',
-                   # If zero arguments are specified (``--debug`` by itself),
-                   # then provide a default argument of all debug options enabled.
-                   const=DEBUG_ALL_CHOICE,
+                   # Allow the user to specify one argument.
+                   nargs=1,
                    # The options specified must come from this list.
                    choices=DEBUG_ALL_CHOICE + DEBUG_ARGUMENT_CHOICES,
                    # Append choice, rather than storing them (which would
@@ -185,12 +182,10 @@ def __add_options(parser):
                    # Allow newlines in the help text; see the
                    # ``_SmartFormatter`` in ``__main__.py``.
                    help=("R|Provide assistance with debugging a frozen\n"
-                         "application, by specifying one or more of the\n"
-                         "following choices.\n"
+                         "application. This argument may be provided multiple\n"
+                         "times to select several of the following options.\n"
                          "\n"
-                         "- all: All three of the below options; this is the\n"
-                         "  default choice, unless one of the choices below is\n"
-                         "  specified.\n"
+                         "- all: All three of the following options.\n"
                          "\n"
                          "- imports: specify the -v option to the underlying\n"
                          "  Python interpreter, causing it to print a message\n"
diff --git a/doc/help2rst.py b/doc/help2rst.py
--- a/doc/help2rst.py
+++ b/doc/help2rst.py
@@ -71,6 +71,10 @@ def process(program, generate_headings, headings_character):
     help = help.strip('\n')
     # escape stars prior to other processing
     help = help.replace('*', r'\*')
+    # Change troublesome argparse text that the optparse-like docutils parser
+    # doesn't understand.
+    help = help.replace('{all,imports,bootloader,noarchive}',
+                        '<all,imports,bootloader,noarchive>')
     if generate_headings:
         program = os.path.splitext(os.path.basename(program))[0].lower()
         help = textwrap.dedent(help)


Test patch: