Add template variables docs and warning about cookiecutter command (#94)

- Add cookiecutter template variables description (fixes #86)
- Add a warning about the cookiecutter command (fixes #93)

Author: llucax

RELEASE_NOTES.md

@@ -16,6 +16,7 @@
 * Bump SDK version to v0.22.0.
 * Capitalize project name in title and expand shortened words.
 * Add a few more default keywords.
+* Add variable reference documentation.
 
 ## Bug Fixes
 

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/hooks/post_gen_project.py

@@ -30,7 +30,7 @@ def to_named_tuple(dictionary: dict[Any, Any], /) -> Any:
     return namedtuple("Cookiecutter", filtered.keys())(*filtered.values())
 
 
-cookiecutter = to_named_tuple(_json.loads("""{{cookiecutter | tojson}}"""))
+cookiecutter = to_named_tuple(_json.loads(r"""{{cookiecutter | tojson}}"""))
 
 
 def main() -> None:

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

@@ -31,21 +31,38 @@ Collecting cookiecutter
 ...
 ```
 
-Then simply run [Cookiecutter] where you want to create the new project. A new
-directory will be created with the generated project name. For example:
+Then simply run [Cookiecutter] where you want to create the new project:
 
 ```sh
-cd ~/devel
-cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter
+cookiecutter gh:frequenz-floss/frequenz-repo-config-python \
+    --directory=cookiecutter
 ```
 
 This command will prompt you for the project type, name, and other
-configuration options, and it will generate the entire project for you.
+configuration options, and it will generate the entire project for you in a new
+subdirectory.
+
+!!! warning
+
+    This command needs to be typed literally!
+
+    `frequenz-floss/frequenz-repo-config-python` is the GitHub repository with
+    the cookiecutter template that will be downloaded, and
+    `--directory=cookiecutter` is needed because the cookiecutter template
+    doesn't live at the top-level of that repository, but in a subdirectory
+    called `cookiecutter`.
+
+    All information about your project will be prompted interactively by that
+    command.
 
 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