Improve new project UX

[ckunki]

Current Situation

Currently, for initializing new projects the PTB uses cookiecutter with the following benefits

• ✅ Can be used before even installing the PTB as dependency
• ✅ Supports interactive dialog with user asking for the required information
• ✅ Includes examples, "Yet Another Project" which give a hint on the expected input format, e.g. capitalized with spaces
• ✅ Can infer derived values from previous inputs, e.g. derive package name and import from project_name "Yet Another Project".

Drawbacks

However, there are some problems, still

• ❌ User is forced to
  • Fill out the values in the defined sequence
  • Complete the initialization without interruptions
• ❌ If the user aborts the initialization they cannot reuse or edit the former inputs, there is no history
• ❌ No edit keys, cursor movement, delete, insert at arbitrary positions
• ❌ Does not provide editable defaults, e.g. when a part of the inferred default value is OK, but still the user might want to change only a part of it.

Vision

In my personal preference is more like

• filling out a form
• Seeing all questions in advance
• being able to stop and continue at any point in time, saving the current state
• use all your editor features, history, copy paste, etc.

Proposed Changes to Cookiecutter Template

• Ask for repo first
• Derive project_name from repo_name rather than the other way round.
• Update default values

  "project_name": "{{cookiecutter.repo_name | title | replace('-', ' ')}}",
  "package_name": "{{cookiecutter.repo_name | replace('-', '.')}}",
  "author_email": "{{cookiecutter.author_full_name | lower | replace(' ', '.')}}@exasol.com",

Update User Guide

Optional Preparation

If you expect to use cookiecutter more often in the future, then you can
create a file ~/.cookiecutterrc with content

default_context:
    author_full_name: <your full name>
    author_email: <your email address>

Alternatively you can specify these values on the command line

cookiecutter ... author_full_name="<your full name>" author_email="<your email address>" 

Adding Initial Content to a New Project

These instructions assume:

• You created your project on GitHub.
• You cloned it to your local file system, e.g. ~/git/repo-name.
• The repo contains a file README.md ending in the initial project description.

Under these preconditions you can add initial content to your project and prepare it using the PTB:

1. Set current directory to the repo you just checked out, e.g. cd ~/git/repo-name.
2. Create a branch git checkout -b refactoring/initial-repo-content
3. Call cookiecutter

   cookiecutter \
       https://github.com/exasol/python-toolbox.git \
       --checkout <latest-tag> \
       --directory project-template \
       --overwrite-if-exists \
       --output-dir .. \
       repo_name="$(basename $(pwd))" \
       description="$(tail -1 README.md)"

If you prefer editing your input in a file rather than answering questions interactively, then you can create a file .cookiecutter.yml with the following content

default_context:
    project_name: Yet Another Project
    repo_name: <repo-name>
    description: <Project Description>
    package_name: <package.name>
    project_short_tag: <XXX>
    author_full_name: <your full name>
    author_email: <your email address>

... and add CLI option --config-file .cookiecutter.yml when calling cookiecutter.