improvement: more useful "create project" yaml

[stefreak]

What this PR does / why we need it:

The previous yaml generated by the docs-generator looked like this:

# Documentation about Garden projects can be found at https://docs.garden.io/using-garden/projects
# Reference for Garden projects can be found at https://docs.garden.io/reference/project-config

# The Garden apiVersion for this project.
#
# The value garden.io/v0 is the default for backwards compatibility with
# Garden Acorn (0.12) when not explicitly specified.
#
# Configuring garden.io/v1 explicitly in your project configuration allows
# you to start using the new Action configs introduced in Garden Bonsai (0.13).
#
# Note that the value garden.io/v1 will break compatibility of your project
# with Garden Acorn (0.12).
apiVersion: garden.io/v1

# Indicate what kind of config this is.
kind: Project

# The name of the project.
name: foobar

# A list of environments to configure for the project.
environments:
  - # The name of the environment.
    name: default

# A list of providers that should be used for this project, and their configuration. Please refer to individual
# plugins/providers for details on how to configure them.
providers:
  - # The name of the provider plugin to use.
    name: local-kubernetes

While it is cool that we are re-using the descriptions from our docs,
there are some problems with this yaml code:

• The comments often do not add any valuable information. For example
  it's already clear that name: foobar is the name of the project.
• Another problem is that the description in the reference docs is not
  necessarily the information a user needs when getting started. This
  becomes apparent in the comment above apiVersion, for example.

This commit simplifies the create project command implementation to
just write a file with hardcoded yaml. The comments are hand-crafted for
a good getting-started experience.

This commit also updates the docs that refer to the "create project"
command.

The new yaml looks like this:

# Documentation about Garden projects can be found at https://docs.garden.io/using-garden/projects
# Reference for Garden projects can be found at https://docs.garden.io/reference/project-config

apiVersion: garden.io/v1
kind: Project
name: test

defaultEnvironment: local

# Environments typically represent different stages of your development and deployment process.
environments:
  # Use this environment to develop in your local Kubernetes solution of choice.
  # Installation instructions and list of supported local Kubernetes environments: https://docs.garden.io/kubernetes-plugins/local-k8s/install
  - name: local
    defaultNamespace: garden-local

  # Use this environment to develop in remote, production-like environments that scale with your stack.
  # This means you don't need any dependencies on your local machine, even the builds can be performed remotely.
  # It enables sharing build and test caches with your entire team, which can significantly speed up pipelines and development.
  - name: remote
    defaultNamespace: garden-remote-${local.username}

  - name: staging
    # Ask before performing potentially destructive commands like "deploy".
    production: true
    defaultNamespace: staging

# Providers make action types available in your Garden configuration and tell Garden how to connect with your infrastructure.
# For example the kubernetes and local-kubernetes providers allow you to use the container, helm and kubernetes action types.
# All available providers and their configuration options are listed in the reference docs: https://docs.garden.io/reference/providers
providers:
  - name: local-kubernetes
    environments:
      - local

  # To configure the remote kubernetes providers, follow the steps at https://docs.garden.io/kubernetes-plugins/remote-k8s
  - name: kubernetes
    environments:
      - remote
    context: # ... your remote development kubecontext here
  - name: kubernetes
    environments:
      - staging
    context: # ... your staging kubecontext here

# Next step: Define actions to tell Garden how to build, test and deploy your code.
# You can find out more here: https://docs.garden.io/using-garden/actions

Which issue(s) this PR fixes:

Fixes #

Special notes for your reviewer:

[stefreak]

The backslash seems to end up in the final yaml file. We need to fix that before merging.

[TimBeyer]

Is that true? In theory that should just escape the $ so it doesn't get templated in JS.

[TimBeyer]

[stefreak]

I'm puzzled about this too. But I ran the command "garden create project" with the dev build, and the backslash was there. 🤔

[stefreak]

@TimBeyer I now worked around this mystery and updated the tests.

[twelvemo]

I think this is great! I have a few suggestions around comments, feel free to adept or discard.

[twelvemo]

Suggested change

	# You could also define a staging environment, which is shared by several developers.

[stefreak]

I decided not to incorporate this one, because it does not add a lot of information– Here I'd value conciseness and usefulness over consistency

[twelvemo]

LGTM! Thanks for improving this!