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.