Prompts with help

This is yet another try at introducing a new cookiecutter.json format which will support specifying help text for individual parameters which will be then printed when prompting.

There’ve been several attempts to do that (#249, #30, #381, #433), but all now seem outdated for one reason or another, so I am opening this new issue. I think old ones should be closed to reduce confusion. I’ve gone through discussions on the above issues/PRs and picked up the good parts.

Ultimately, I would love cookiecutter to be able to prompt for parameters similarly to how sphinx-quickstart does:

New cookiecutter.json format

Backwards compatibility has to be considered when designing a new cookiecutter.json format. First, the current version of cookiecutter should handle the new format. Second, new cookiecutter should support old format.

I propose this new format:

{
    // old way of specifying parameters is to keep backwards compatibility
    // of the new format with the old cookiecutter executables
    // which do not support the new '_parameters' section yet
    // it will be overwritten by '_parameters' by the new cookiecutter
    "directory_name": "default_directory_name",

    // '_parameters' section will be ignored by the old cookiecutter executables
    // for new cookiecutter '_parameters' section will be the main way of specifying parameters
    // old proposals prefer the name '_context' for this section, but I think that '_parameters' is more self-explaining. hmm?
    "_parameters": {
        "directory_name": {
            "default_value": "default_directory_name",
            "prompt": "Name of the directory which will contain the generated project",
            "help": "This will be the root of the new project. bla bla."
        }
    },

    // '_required_cookiecutter_version' is not strictly required for now,
    // but it will make our lives much easier in the future
    // it should be a separate PR for sure, so just including it here to show this option
    "_required_cookiecutter_version": "2.1.3"
}

This format will fully handle the backwards compatibility. I acknowledge that writing cookiecutter.json will be more difficult from now on, but I think that is an acceptable tradeoff. After all, cookiecutter.json is written once, but used many many times, so I prefer to optimize for the end user experience.

What do you think?

If main contributors are happy with the proposal, I can take care of the code and documentation changes.

[Cadair]

Why not add a section to the JSON just for help prompts that can be ignored by old versions and is independent of the values.

{
    // Still use this format for specifying variables
    "directory_name": "default_directory_name",

    // extra help dictionary maps to above structure. 
    // This could have nested dicts to handle nested prompts.
    "_help": {
        "directory_name": {
            "prompt": "Name of the directory which will contain the generated project",
            "help": "This will be the root of the new project. bla bla."
        }
    },
}

[nicktimko]

Has this been subsumed by some other issue and/or implemented elsewhere? #848 also looks stalled, but also looks gigantic.

Right now the workaround I have is to print some help text after the user enters all their variables via a pre_gen_project hook and explain why that variable you entered is invalid. That’s kinda frustrating if there are a bunch.

Another workaround I concocted is like the below (and just do nothing with helpX’s)

{
  "help1": "The maintainers should be GitHub usernames. Enter to continue...",
  "primary_maintainer": "",
  "secondary_maintainer": "",
  "help2": "The 'app_name' must be a valid Python module name. Enter to continue...",
  "app_name": "example"
}

---

help1 [The maintainers should be GitHub usernames. Enter to continue...]:        
primary_maintainer []: nicktimko                                                 
secondary_maintainer []:                                                         
help2 [The 'app_name' must be a valid Python module name. Enter to continue...]: 
app_name [example]:                                                              

Are there any better alternatives meanwhile?