Repository: spack/spack

Issue:
docs: Alphabetize create cmd template options
Noticed the docs --and ``spack create -h``-- were showing a format option instead of the template choices so this change fixes (or should) this problem.

UPDATE:  Changed to only alphabetize the options given #14014 fix.


Discussion:
I'm confused, the current behavior works for me:
```console
$ spack create -h
usage: spack create [-hf] [--keep-stage] [-n NAME] [-t TEMPLATE] [-r REPO]
                    [-N NAMESPACE] [--skip-editor]
                    [url]

create a new package file

positional arguments:
  url                   url of package archive

optional arguments:
  -h, --help            show this help message and exit
  --keep-stage          don't clean up staging area when command completes
  -n NAME, --name NAME  name of the package to create
  -t TEMPLATE, --template TEMPLATE
                        build system template to use. options: autotools, autoreconf, cmake, bundle, qmake, scons, waf, bazel, python, r, perlmake, perlbuild, octave, makefile, intel, meson, sip, generic
  -r REPO, --repo REPO  path to a repository where the package should be created
  -N NAMESPACE, --namespace NAMESPACE
                        specify a namespace for the package. must be the namespace of a repository registered with Spack
  -f, --force           overwrite any existing package file with the same name
  --skip-editor         skip the edit session for the package (e.g., automation)
```
This behavior is documented at: https://docs.python.org/3/library/argparse.html#help

> The help strings can include various format specifiers to avoid repetition of things like the program name or the argument default. The available specifiers include the program name, %(prog)s and most keyword arguments to add_argument(), e.g. %(default)s, %(type)s, etc.:
Interesting. Maybe it’s a python version specific thing?

I noticed the issue in Spack's readthedocs.
Yep, it definitely looks broken in https://spack.readthedocs.io/en/latest/command_index.html#spack-create.

Locally, things work for both Python 2 and 3, which makes sense as we vendor our argparse module. I wonder if it's due to some kind of hack we did for our argparse support?
> Interesting. Maybe it’s a python version specific thing? I noticed the issue in Spack's readthedocs.

FWIW I stand corrected.  I _thought_ it didn't show up properly yesterday on one of the machines I use for me in `spack create -h` but that does not appear to be the case.
> Yep, it definitely looks broken in https://spack.readthedocs.io/en/latest/command_index.html#spack-create.
> 
> Locally, things work for both Python 2 and 3, which makes sense as we vendor our argparse module. I wonder if it's due to some kind of hack we did for our argparse support?

Idk.  But I have confirmed this fix will produce the list (instead of "%(choices)s") in the docs.  I also alphabetized the list for readability.
It looks like the Command Index docs are generated by running `spack commands --format=rst`. We might be able to hack `spack commands` to get things to work the way they should.

Resolving patch:
diff --git a/lib/spack/llnl/util/argparsewriter.py b/lib/spack/llnl/util/argparsewriter.py
--- a/lib/spack/llnl/util/argparsewriter.py
+++ b/lib/spack/llnl/util/argparsewriter.py
@@ -10,9 +10,10 @@
 import sys
 
 
-class ArgparseWriter(object):
+class ArgparseWriter(argparse.HelpFormatter):
     """Analyzes an argparse ArgumentParser for easy generation of help."""
     def __init__(self, out=sys.stdout):
+        super(ArgparseWriter, self).__init__(out)
         self.level = 0
         self.out = out
 
@@ -48,7 +49,7 @@ def _write(self, parser, root=True, level=0):
         def action_group(function, actions):
             for action in actions:
                 arg = fmt._format_action_invocation(action)
-                help = action.help if action.help else ''
+                help = self._expand_help(action) if action.help else ''
                 function(arg, re.sub('\n', ' ', help))
 
         if root:


Test patch: