Addressed usability issues encountered when generating a project (#13)

Author: davidbrownell

src/PopulateCookiecutterPrompts.py

@@ -63,9 +63,7 @@ def Replace(
                     ",\n".join(
                         '"{}": "{}"'.format(
                             key,
-                            "\n\n{}{}".format(value, "\n\n" if "\n" in value else "")
-                            .replace("\n", "\\n")
-                            .replace('"', '\\"'),
+                            "\n\n{}\n\n".format(value).replace("\n", "\\n").replace('"', '\\"'),
                         )
                         for key, value in yaml_content.items()
                     ),

src/PythonProjectBootstrapper/package/cookiecutter.json

@@ -20,7 +20,7 @@
     "gist_id": "<your gist id>",
     "gist_username": "{{ cookiecutter.github_username }}",
 
-    "create_docker_image": "no",
+    "create_docker_image": false,
 
     "__empty_dir": "",
 
@@ -36,7 +36,7 @@
         "github_project_name": "\n\nPlease enter your GitHub project name. You should use the URL to your GitHub repository as a guide\nwhen specifying this value.\n\n    https://github.com/username/projectname\n                                ^^^^^^^^^^^\n                                This is the GitHub project name\n\n",
         "pypi_project_name": "\n\nPlease enter the name of your project as it will appear on PyPI (https://pypi.org). This\nname cannot be associated with any other project on PyPI.\n\n",
         "gist_id": "\n\nPlease enter the GitHub gist id for use with this project.\n\nGitHub defines a gist as \"a simple way to share snippets and pastes with others.\" The generated\npython project will use a gist to store information dynamically generated during the build (for\nexample code coverage information) that can be retrieved at a later time (for example, to display\na code coverage badge in the project's README.md file).\n\nTo create a gist:\n    1. Go to https://gist.github.com/\n    2. Enter the following values in their respective fields:\n\n        Gist description...:                Gist used by GitHub Action workflows to store and retrieve dynamic information (oftentimes used to create and display badges).\n        Filename including extension...:    README.md\n        File contents:                      Gist used by GitHub Action workflows to store and retrieve dynamic information (oftentimes used to create and display badges).\n\n    3. Click the \"Create secret gist\" button\n    4. Copy the gist id (this will be the hex string at the end of the url associated with the gist\n       that was just created). It will look something like:\n\n          https://gist.github.com/<github username>/4c10281ff1abc26cafcb9a5f9a8a443e\n                                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n                                                           This is the gist id\n\n",
-        "gist_username": "\n\nPlease enter the username associated with your gist_id. In most cases, this will be the same as your GitHub username.",
+        "gist_username": "\n\nPlease enter the username associated with your gist_id. In most cases, this will be the same as your GitHub username.\n\n",
         "create_docker_image": "\n\nWould you like the GitHub Action workflows to create docker images of the development environment?\nThese images can be used to produce exact results across different commits made to the repository\nover time (which is especially valuable when writing scientific software).\n\n"
     },
 

src/PythonProjectBootstrapper/package/cookiecutter_prompts.yaml

@@ -84,6 +84,7 @@ gist_id: |-
             https://gist.github.com/<github username>/4c10281ff1abc26cafcb9a5f9a8a443e
                                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                                              This is the gist id
+
 gist_username: |-
   Please enter the username associated with your gist_id. In most cases, this will be the same as your GitHub username.
 

src/PythonProjectBootstrapper/package/hooks/post_gen_project.py

@@ -18,11 +18,10 @@
 
 
 # ----------------------------------------------------------------------
-_prompts: dict[str, str] = {
+_prefix_prompts: dict[str, str] = {
     "GitHub Personal Access Token for gists": textwrap.dedent(
         """\
-        In this step, we will create a GitHub Personal Access Token (PAT) that is used to
-        update the gist that stores dynamic build data.
+        In this step, we will create a GitHub Personal Access Token (PAT) that is used to update the gist that stores dynamic build data.
 
         1. Visit {{ cookiecutter.github_url }}/settings/tokens?type=beta
         2. Click the "Generate new token" button
@@ -54,16 +53,13 @@
     ),
     "Temporary PyPi Token to Publish Packages": textwrap.dedent(
         """\
-        In this step, we will create a PyPi token that is used to publish python packages. Note
-        that this token will be scoped to all of your projects on PyPi. Once the package is
-        published for the first time, we will delete this token and create one that is scoped to
-        a single project.
+        In this step, we will create a PyPi token that is used to publish python packages. Note that this token will be scoped to all of your projects on PyPi. Once the package is published for the first time, we will delete this token and create one that is scoped to a single project.
 
         1. Visit https://pypi.org/manage/account/
         2. Click the "Add API token" button
         3. Enter the values:
-                Token name:    "Temporary GitHub Publish Action ({{ cookiecutter.github_project_name }})"
-                Scope:         "Entire account (all projects)"
+                Token name:    Temporary GitHub Publish Action ({{ cookiecutter.github_project_name }})
+                Scope:         Entire account (all projects)
         4. Click the "Create token" button
         5. Click the "Copy token" button for use in the next step
         """,
@@ -81,38 +77,50 @@
         5. Click the "Add secret" button
         """,
     ),
-    "Commit and Push the Repository": textwrap.dedent(
+}
+
+if {{cookiecutter.create_docker_image}}:
+    _prefix_prompts["Update GitHub Seettings"] = textwrap.dedent(
         """\
-        In this step, we commit the files generated in git, push the changes in GitHub, and verify
-        that the GitHub Actions workflow ran successfully.
+        In this step, we will update GitHub settings to allow pushing the generated docker image to the GitHub Container Registry during the build.
+
+        1. Visit {{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/settings/actions
+        2. In the "Workflow permissions" section...
+        3. Select "Read and write permissions"
+        4. Click the "Save" button
+        """,
+    )
 
-        Commit and Push the Changes
-        ---------------------------
-        Note that these steps assume that the GitHub repository has already been created.
+_prompts: dict[str, str] = {
+    "Commit and Push the Repository": textwrap.dedent(
+        """\
+        In this step, we commit the files generated in git and push the changes to GitHub. Note that these steps assume that the GitHub repository has already been created.
 
         From a terminal:
 
         1. Run 'git add -all'
         {windows_command}{commit_step_num}. Run 'git commit -m "🎉 Initial commit"'
         {push_step_num}. Run 'git push'
-
-        Verify the GitHub Actions Workflow
-        ----------------------------------
-        1. Visit {{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/actions
-        2. Click on the most recent workflow
-        3. Wait for the workflow to complete
         """,
     ).format(
         windows_command=(
-            "2. git update-index --chmod=+x Bootstrap.sh\n" if os.name == "nt" else ""
+            "2. Run 'git update-index --chmod=+x Bootstrap.sh'\n" if os.name == "nt" else ""
         ),
         commit_step_num="3" if os.name == "nt" else "2",
         push_step_num="4" if os.name == "nt" else "3",
     ),
+    "Verify GitHub Actions": textwrap.dedent(
+        """\
+        In this step, we will verify that the GitHub Action workflows ran successfully.
+
+        1. Visit {{ cookiecutter.github_url }}/{{ cookiecutter.github_username }}/{{ cookiecutter.github_project_name }}/actions
+        2. Click on the most recent workflow
+        3. Wait for the workflow to complete
+        """,
+    ),
     "Remove Temporary PyPi Token": textwrap.dedent(
         """\
-        In this step, we will delete the temporary PyPi token previously created. A new token to replace
-        it will be created in the steps that follow.
+        In this step, we will delete the temporary PyPi token previously created. A new token to replace it will be created in the steps that follow.
 
         1. Visit https://pypi.org/manage/account/
         2. Find the token named "Temporary GitHub Publish Action ({{ cookiecutter.github_project_name }})"...
@@ -130,8 +138,8 @@
         1. Visit https://pypi.org/manage/account/
         2. Click the "Add API token" button
         3. Enter the values:
-                Token name:    "GitHub Publish Action ({{ cookiecutter.github_project_name }})"
-                Scope:         "Project: {{ cookiecutter.pypi_project_name }}"
+                Token name:    GitHub Publish Action ({{ cookiecutter.github_project_name }})
+                Scope:         Project: {{ cookiecutter.pypi_project_name }}
         4. Click the "Create token" button
         5. Click the "Copy token" button for use in the next step
         """,
@@ -179,16 +187,20 @@ def UpdateLicenseFile():
 # ----------------------------------------------------------------------
 def DisplayPrompts():
     border_colors = itertools.cycle(
-        ["green", "yellow", "blue", "magenta", "cyan"],
+        ["yellow", "blue", "magenta", "cyan", "green"],
     )
 
-    for prompt_index, (title, prompt) in enumerate(_prompts.items()):
+    sys.stdout.write("\n\n")
+
+    prompts = list(itertools.chain(_prefix_prompts.items(), _prompts.items()))
+
+    for prompt_index, (title, prompt) in enumerate(prompts):
         print(
             Panel(
-                prompt.strip(),
+                prompt.rstrip(),
                 border_style=next(border_colors),
                 padding=1,
-                title=f"[{prompt_index + 1}/{len(_prompts)}] {title}",
+                title=f"[{prompt_index + 1}/{len(prompts)}] {title}",
                 title_align="left",
             ),
         )

src/PythonProjectBootstrapper/package/hooks/startup.py

@@ -33,7 +33,7 @@ def Execute(
         step-by-step instructions on how to set up your project so that it works with 3rd party
         solutions (GitHub, PyPi, etc.).
 
-        The entire process should take about 10 minutes to complete.
+        The entire process should take about 20 minutes to complete.
         """,
     )