Added support for providing human-readable prompts to the different variables

[vemonet]

Hi @pydanny @jensens @ericof @audreyfeldroy, I added support for providing human-readable questions to the different variables

Many issues mentioned it:

• Support better prompts #30
• New config file format #249
• Prompts with help #794
• New cookiecutter.json format and more for cookiecutter 2.0 #1567
• Add parameter description field to cookiecutter.json #1835

A PR has been attempted but abandonned: #848

There have been lengthy discussions about wherever the json format should completely be changed, introduce breaking change, etc... I took the simplest approach, to introduce the least amount of technical debt and keep complete backward compatibility . So that we can merge this feature, really much needed for a templating library, and discuss about changing the JSON format later!

It was quite straightforward to implement, I just added a __prompts__ object, which takes the variable names as key and the questions to ask the user as values.

Example of a config file:

{
    "package_name": "my-package",
    "module_name": "{{ cookiecutter.package_name.replace('-', '_') }}",
    "short_description": "A nice python package",
    "__prompts__": {
        "package_name": "Select your package name:",
        "module_name": "Select your module name:"
    }
}

The 2 first questions will use the description provided, the 3rd one will use the variable name since there is no description provided

This format stays easy to read, and easy to write. Once the dev defined all its variables with their default they can copy them, paste them in the __prompts__ block, and replace the default by the questions one by one. Also wrap something around 2 underscores is a pythonic way to say "this is special" (__init__, __main__)

In my opinion when you have many variables it is more readable than a nested dict where some keys are repeated all other the place

{
    "package_name": {
        "default": "my-package", 
        "prompts": "Your package name",
    },
    "module_name": {
        "default": "{{ cookiecutter.package_name.replace('-', '_') }}", 
        "prompts": "Your package name",
    },
}

It is 100% backward compatible with the previous cookiecutter.json format 🎉 so it will not break existing template, it will only make templates that have defined __prompts__ better!

• Not a lot of code have been added, and the changes introduced don't introduce a lot of complexity in the codebase
• I made sure all tests pass with tox, and I added a few tests for the new feature, to reach 💯% of code coverage
• I have updated the example in the README to show how to use those new descriptions
• A page has been added in the advanced tab in readthedocs documentation

I hope there is no more excuses to not merge this long-awaited feature 😄 I am already using it for my templates and will continue in the future since those templates are fully compatible!

There are no breaking changes so this feature can be pushed to the next minor release without any concern 🥳

Please let me know if we should use something else instead of __prompts__, I can make the changes required in a few minutes (maybe _prompts_ with only 1 underscore? that might be less prone to user mistakes, but the double underscore seems more pythonic)

[ericof]

Thanks, @vemonet! As soon as the tests pass, I will merge this!

[ericof]

Great addition!

[henryiii]

Does this support customizing choice prompts? I'd like to show something more helpful for selecting choices, but don't see how this fits into this structure. If I provided a dict here, how would I customize the top level prompt? Maybe a special key?

{
    "__prompts__": {
        "backend": { 
            "__prompt__": "Select a backend to build your package:",
            "setuptools": "Classic setuptools configuration",
            "setuptools621": "Modern pyproject.toml setuptools configuration"
       }
    }
}

?

(This is great, by the way!)

[vemonet]

Hi @henryiii , it does not support this, but is an interesting suggestion

And the solution you proposed is nice, and the easiest to implement I think. I'll take a look into it when I will have time

A complete JSON would look like this:

{
    "package": "my-package",
    "backend": [
         "setuptools", 
         "setuptools621"
    ],
    "__prompts__": {
        "package": "Your package slug",
        "backend": { 
            "__prompt__": "Select a backend to build your package:",
            "setuptools": "Classic setuptools configuration",
            "setuptools621": "Modern pyproject.toml setuptools configuration"
       }
    }
}