Add cookiecutter template variables description

The description of the variables will be printed before they are
prompted when generating a new project, and will be also included in the
documentation website.

To show the help before the project generation we need to use a very
dirty hack as cookiecutter doesn't support a hook that runs before the
variables are printed. So to do that we hijack a cookiecutter variable
itself ("Introduction") to display the help in the default text.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

cookiecutter/cookiecutter.json

@@ -1,4 +1,5 @@
 {
+	"Introduction": "{{cookiecutter | introduction}}",
 	"type": [
 		"actor",
 		"api",
@@ -25,6 +26,7 @@
 		"jinja2_time.TimeExtension",
 		"local_extensions.default_codeowners",
 		"local_extensions.github_repo_name",
+		"local_extensions.introduction",
 		"local_extensions.keywords",
 		"local_extensions.pypi_package_name",
 		"local_extensions.python_package",

cookiecutter/local_extensions.py

@@ -8,6 +8,7 @@
 """
 
 import json as _json
+import pathlib as _pathlib
 
 from cookiecutter.utils import simple_filter as _simple_filter
 
@@ -191,3 +192,30 @@ def default_codeowners(cookiecutter: dict[str, str]) -> str:
     assert repo_type in type_to_team, f"Unhandled repository type {repo_type!r}"
 
     return type_to_team[repo_type]
+
+
+@_simple_filter  # type: ignore[misc]
+def introduction(
+    cookiecutter: dict[str, str]  # pylint: disable=unused-argument
+) -> str:
+    """Build an introduction text for the project generation.
+
+    Args:
+        cookiecutter: The cookiecutter context.
+
+    Returns:
+        The introduction text.
+    """
+    with (_pathlib.Path(__file__).parent / "variable-reference.md").open() as doc_file:
+        variable_reference = doc_file.read()
+    return f"""]
+
+Welcome to repo-config Cookiecutter template!
+
+This template will help you to create a new repository for your project. You will be asked to provide some information about your project.
+
+Here is an explanation of what each variable is for and will be used for:
+
+{variable_reference}
+
+[Please press any key to continue"""

cookiecutter/variable-reference.md

@@ -0,0 +1,50 @@
+* `type`: The type of repository. It must be chosen from the list.
+
+* `name`: The name of the project. This will be used to build defaults for
+  other inputs, such as `title`, `python_package`, etc. It should be one word,
+  using only alphanumeric characters (and starting with a letter).
+
+* `description`: A short description of the project. It will be used as the
+  description in the `README.md`, `pyproject.toml`, `mkdocs.yml`, etc.
+
+* `title`: A human-readable name or title for the project. It will be used in
+  the `README.md`, `CONTRIBUTING.md`, and other files to refer to the project,
+  as well as the site title in `mkdocs.yml`.
+
+* `keywords`: A comma-separated list of keywords that will be used in the
+  `pyproject.toml` file. If left untouched, it will use only some predefined
+  keywords. If anything else is entered, it will be **added** to the default
+  keywords.
+
+* `github_org`: The GitHub handle of the organization where the project will
+  reside. This will be used to generate links to the project on GitHub.
+
+* `license`: Currently, only two options are provided: `MIT`, which should be
+  used for open-source projects, and `Proprietary`, which should be used for
+  closed-source projects. This will be added to file headers and used as the
+  license in `pyproject.toml`.
+
+* `author_name`, `author_email`: The name and email address of the author of
+  the project. They will be used in the copyright notice in file headers and
+  as the author in `pyproject.toml`.
+
+* `python_package`: The Python package in which this project will reside. All
+  files provided by this project should be located in this package. This needs
+  to be a list of valid Python identifiers separated by dots. The source file
+  structure will be derived from this. For example, `frequenz.actor.example`
+  will generate files in `src/frequenz/actor/example`.
+
+* `pypi_package_name`: The name of the PyPI/wheel/distribution package. This
+  should be consistent with the `python_package`, usually replacing `.` with
+  `-`. For example, `frequenz-actor-example`.
+
+* `github_repo_name`: The handle of the GitHub repository where the project
+  will reside. This will be used to generate links to the project on GitHub and
+  as the top-level directory name.
+
+* `default_codeowners`: A space-separated list of GitHub teams (`@org/team`) or
+  users (`@user`) that will be the default code owners for this project. This
+  will be used to build the `CODEOWNERS` file. Please refer to the [code owners
+  documentation] for more details on the valid syntax.
+
+[code owners documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners

docs/index.md

@@ -46,6 +46,10 @@ After completing the project and fixing the `TODO`s, you can either amend the
 previous commit using `git commit --amend` or create a new commit for the
 changes using `git commit`.
 
+### Template variables reference
+
+--8<-- "cookiecutter/variable-reference.md"
+
 ### Create the local development environment
 
 To start development, you need to make sure your environment is correctly set

mkdocs.yml

@@ -108,6 +108,7 @@ plugins:
 
 # Preview controls
 watch:
+  - "cookiecutter/variable-reference.md"
   - "src"
   - README.md
   - CONTRIBUTING.md