Improve the error message & docstring of `kedro new` for custom starters

[noklam]

Part of #2604

Context

The error message of kedro new is not very accurate. This was found when we try to use kedro new for a new starter that haven't been added to the official starters list.

There are at least 2 common ways (Added more if found)

1. kedro new -s pandas-iris , using kedro new for official starters

2. kedro new --starter <some_directory> --checkout <branch> --directory <directory>, use it for custom starters in local or repository (not documented)

3. should be documented as it is not easy to figure out with the docstring and CLI help message. In addition, the error message isn't accurate

    if starter_alias in starters_dict:
        if directory:
            raise KedroCliError(
                "Cannot use the --directory flag with a --starter alias."
            )

This is very confusing because to do 2. you need to use both starter and directory, but the error message says the opposite.

i.e. kedro new --starter git+https://github.com/kedro-org/kedro-starters.git --directory databricks-iris --checkout feat/modify-pyspark-iris-databricks-packaged-deployment (This works)

The help message have some information about --starter flag can be provided as a git URL

The help message actually provide more accurate information.

 -s, --starter TEXT  Specify the starter template to use when creating the
                      project. This can be the path to a local directory, a
                      URL to a remote VCS repository supported by
                      `cookiecutter` or one of the aliases listed in ``kedro
                      starter list``.

Action

• Improve the docstring or error message or both, add example to make it easier to discover the feature.

[MinuraPunchihewa]

Hey @astrojuanlu, @merelcht, I would like to take this up!

[astrojuanlu]

Hi @MinuraPunchihewa , thanks for stepping in! @AhdraMeraliQB does this somehow conflict with the new add-ons flow?

[AhdraMeraliQB]

CC: @noklam

This is very confusing because to do 2. you need to use both starter and directory, but the error message says the opposite.

The error message results if an official Kedro starter-alias is used with --directory, hence why using a git url works. Perhaps the issue here is that the error message "Cannot use the --directory flag with a --starter alias." is not clear enough?

Option: "Cannot use the --directory flag with a Kedro starter alias."

I agree that this should be visibly documented, an addition should be made to https://docs.kedro.org/en/stable/starters/starters.html, but I'm unsure the error message itself needs to be modified

[doxenix]

PR is ready: https://github.com/kedro-org/kedro/pull/3771 I only updated docs and add more examples. I agree with @AhdraMeraliQB that error message itself dosen't needs to be modified

[astrojuanlu]

This was addressed in #3771!