feat: prompt messages

CHANGELOG.rst

@@ -5,6 +5,13 @@ Change Log
    This file loosely adheres to the structure of https://keepachangelog.com/,
    but in reStructuredText instead of Markdown.
 
+2024-05-25
+**********
+
+- Prompts added to all cookiecutters.
+- "models" default value in django-app cookiecutter changed to "No Model"
+- All README files updated.
+
 2024-04-30
 **********
 

README.rst

@@ -3,8 +3,6 @@ edx-cookiecutters
 
 This repository holds most of the Open edX public cookiecutters.
 
-
-
 Available cookiecutters
 ***********************
 
@@ -18,15 +16,16 @@ cookiecutter-python-library
     for creating a Python package that follows Open edX standards.
 
 cookiecutter-xblock
-    for creating a XBlock repository as well as a Dockerfile for building and running your XBlock in the xblock-sdk workbench.
+    for creating an XBlock repository and a Dockerfile for building and running your XBlock in the xblock-sdk workbench.
 
 
 Using the cookiecutters
 ***********************
 
 1. One Time Setup
 =================
-.. code-block::
+
+.. code-block:: bash
 
   # Clone the repository
   git clone [email protected]:openedx/edx-cookiecutters.git
@@ -40,19 +39,20 @@ Using the cookiecutters
 
 These instructions assume you have cloned this repository and are currently in its head dir. You will need a virtualenv for running the cookiecutter. You can discard it once the cookiecutter has made your new repo.
 
-Commands::
+.. code-block:: bash
+
+    make requirements  # from inside edx-cookiecutter repo
 
-    $ make requirements  # from inside edx-cookiecutter repo
     # Replace <OUTPUT-DIRECTORY> with the base directory; your new directory will go inside.
     # Replace <COOKIECUTTER-NAME> with one of the available cookiecutters documented above.
-    $ cookiecutter -o <OUTPUT-DIRECTORY> <COOKIECUTTER-NAME>
+    cookiecutter -o <OUTPUT-DIRECTORY> <COOKIECUTTER-NAME>
 
 3. TODOs after running cookiecutter
 ===================================
 
-- Modify project README
-- Modify the "requirements upgrade workflow" at ".github/workflows/upgrade-python-requirements.yml" and add "team_reviewers" and the "email_address" of the team/person
-- Modify project docs/decisions/0001-purpose-of-this-repo.rst ADR
+- Modify project ``README.rst``.
+- Modify the "requirements upgrade workflow" at ``.github/workflows/upgrade-python-requirements.yml`` and add ``team_reviewers`` and the ``email_address`` of the team/person.
+- Modify project ``docs/decisions/0001-purpose-of-this-repo.rst`` ADR.
 - Commit and push to GitHub
 - On GitHub, update repo's "About" description
 
@@ -62,12 +62,15 @@ Updating cookiecutters
 If you find anything that is outdated in the cookiecutters in this repository, please create a PR with updates.
 
 
-.. Note:: Some of the cookiecutters in this repository use the layered cookiecutter approach. If you are modifying these, please see "Local Debugging of the layered cookiecutters" section below.
+**Note:** Some of the cookiecutters in this repository use the layered cookiecutter approach. If you are modifying these, please see `Local Debugging of the layered cookiecutters`_ section below.
+
+.. _Local Debugging of the layered cookiecutters: #local-debugging-of-the-layered-cookiecutters
 
 
 Directions for contributing to this repository
 ==============================================
-.. code-block::
+
+.. code-block:: bash
 
   # Clone the repository
   git clone [email protected]:openedx/edx-cookiecutters.git
@@ -123,16 +126,20 @@ Local Debugging of the layered cookiecutters
 --------------------------------------------
 
 To ensure that the layered cookiecutters pull from your local code,
-instead of GitHub, run cookiecutter like::
+instead of GitHub, run cookiecutter like:
+
+.. code-block:: bash
 
-    $ make cookiecutter-<TEMPLATE-NAME>
+    make cookiecutter-<TEMPLATE-NAME>
 
-eg::
+eg:
 
-    $ make cookiecutter-django-app
-    $ make cookiecutter-django-ida
-    $ make cookiecutter-python-library
-    $ make cookiecutter-xblock
+.. code-block:: bash
+
+    make cookiecutter-django-app
+    make cookiecutter-django-ida
+    make cookiecutter-python-library
+    make cookiecutter-xblock
 
 
 Decisions
@@ -152,9 +159,7 @@ License
 =======
 
 The code in this repository is licensed under the Apache Software License 2.0 unless
-otherwise noted.
-
-Please see ``LICENSE.txt`` for details.
+otherwise noted. Please see `LICENSE.txt`_ for details.
 
 
 Reporting Security Issues

cookiecutter-django-app/README.rst

@@ -1,12 +1,12 @@
 Cookiecutter Django Package
 ###########################
 
-A cookiecutter_ template for creating reusable Django packages (installable apps) quickly.
+A `cookiecutter`_ template for creating reusable Django packages (installable apps) quickly.
 If you're creating a standalone Django service, you should probably use
 `cookiecutter-django-ida`_ instead.
 
 
-.. _Cookiecutter: https://github.com/audreyr/cookiecutter
+.. _cookiecutter: https://cookiecutter.readthedocs.org/en/latest/index.html
 .. _cookiecutter-django-ida: https://github.com/openedx/edx-cookiecutters/tree/master/cookiecutter-django-ida
 
 
@@ -29,56 +29,62 @@ it ``blogging_for_humans``) and set up your virtual environment with your
 favorite method.  If you are an edX employee, request a new repo in the
 ``edx`` organization by submitting an ITSUPPORT ticket.  Details are in the
 `How to request a new GitHub repo`_ wiki page. This ticket should also
-request that Github Actions and Codecov be enabled for the new repository.
+request that GitHub Actions and Codecov be enabled for the new repository.
 
 .. _How to request a new GitHub repo: https://openedx.atlassian.net/wiki/pages/viewpage.action?pageId=70385719
 
-**Note**: Your project will be created with README.rst file containing a pypi
-badge, a Github Actions CI badge and a link to documentation on readthedocs.org. You
+**Note**: Your project will be created with a ``README.rst`` file containing a Pypi
+badge, a GitHub Actions CI badge, and a link to documentation on `readthedocs.org`_. You
 don't need to have these accounts set up before using Cookiecutter or
-cookiecutter-django-app.
-
+``cookiecutter-django-app``.
 
 To create a project using this cookiecutter, follow the instructions found in edx-cookiecutter's `readme`_.
 
+.. _readthedocs.org: https://readthedocs.org
 .. _readme: https://github.com/openedx/edx-cookiecutters/blob/master/README.rst
 
+
 After the new folder is created, you will need to:
 
-Enter the project and take a look around::
+Enter the project and take a look around:
 
-    $ cd blogging_for_humans/
-    $ ls
+.. code-block:: bash
+
+    cd blogging_for_humans/
+    ls
 
 Generate a virtualenv and generate requirements files with dependencies
-pinned to current versions (make sure you're using pip 9.0.2+ and Python 3.8)::
+pinned to current versions (make sure you're using pip 9.0.2+ and Python 3.8):
 
-    $ mkvirtualenv Blogging-for-humans
-    $ make upgrade
+.. code-block:: bash
 
-Create a GitHub repo and push it there::
+    mkvirtualenv Blogging-for-humans
+    make upgrade
 
-    $ git init
-    $ git add .
-    $ git commit -m "first awesome commit"
-    $ git remote add origin [email protected]:edx/blogging_for_humans.git
-    $ git push -u origin master
+Create a GitHub repo and push it there:
 
-Now take a look at your repo. Awesome, right?
+.. code-block:: bash
 
+    git init
+    git add .
+    git commit -m "first awesome commit"
+    git remote add origin [email protected]:edx/blogging_for_humans.git
+    git push -u origin master
+
+Now take a look at your repo. Awesome, right?
 
 Address TODOs
 =============
 
 Look around in the new repo for sections marked `TODO`.  Here are a few known
 places where they may appear:
 
-* `openedx.yaml`: Various OEP states need to be updated.  See `OEP-2\: Repository Metadata`_ for more information.
-* `{{cookiecutter.app_name}}/models.py`: If you specified any models to generate, the various docstrings need to be filled in, and PII annotations need to be added.  See `OEP-30\: PII Markup and Auditing`_ for more information on PII annotations.
-* `tests/test_models.py`: Fill in docstrings here too.
+* ``openedx.yaml``: Various OEP states need to be updated.  See `OEP-2 - Repository Metadata`_ for more information.
+* ``{{cookiecutter.app_name}}/models.py``: If you specified any models to generate, the various docstrings need to be filled in, and PII annotations need to be added.  See `OEP-30 - PII Markup and Auditing`_ for more information on PII annotations.
+* ``tests/test_models.py``: Fill in docstrings here too.
 
-.. _OEP-2\: Repository Metadata: https://open-edx-proposals.readthedocs.io/en/latest/oep-0002-bp-repo-metadata.html
-.. _OEP-30\: PII Markup and Auditing: https://open-edx-proposals.readthedocs.io/en/latest/oep-0030-arch-pii-markup-and-auditing.html
+.. _OEP-2 - Repository Metadata: https://docs.openedx.org/projects/openedx-proposals/en/latest/archived/oep-0002-bp-repo-metadata.html
+.. _OEP-30 - PII Markup and Auditing: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0030-arch-pii-markup-and-auditing.html
 
 Finally, it's time to write the code!!!
 
@@ -88,19 +94,19 @@ Running Tests
 
 Code has been written, but does it actually work? Let's find out!
 
-::
+.. code-block:: bash
 
     workon <YOURVIRTUALENV>
     (myenv) $ make requirements
     (myenv) $ make test-all
 
 
-Github Checks
+GitHub Checks
 =============
 
 On your first PR, ensure Github Actions and Codecov checks are running.
 
-If Github Actions are not running, you can look their state here https://github.com/openedx/edx-cookiecutters/actions
+If Github Actions are not running, you can look at their state here https://github.com/openedx/edx-cookiecutters/actions
 
 If Codecov is not running, complete an ITSUPPORT ticket.
 
@@ -113,7 +119,7 @@ register the application on PyPI.
 You should use PyPa's official Github action: https://github.com/marketplace/actions/pypi-publish
 to publish your package to PyPi in your Github workflow file you'd need to add the following
 
-::
+.. code-block:: yaml
 
     - name: Publish the package to PyPi
       uses: pypa/gh-action-pypi-publish@master
@@ -122,18 +128,20 @@ to publish your package to PyPi in your Github workflow file you'd need to add t
         password: ${{ secrets.PYPI_UPLOAD_TOKEN }}
 
 
-``PY_UPLOAD_TOKEN`` is available organization wide edX repos via Github secrets.
+``PY_UPLOAD_TOKEN`` is available organization-wide Open edX repos via Github secrets.
 
 Releasing on PyPI
 =================
 
 Time to release a new version? Update the version number in the application
-module's ``__init__.py`` file, update ``CHANGELOG.rst`` accordingly, and run::
+module's ``__init__.py`` file, update ``CHANGELOG.rst`` accordingly, and run:
+
+.. code-block:: bash
 
-    $ python setup.py tag
+    python setup.py tag
 
-and create a Github release with new tag, your Github workflow should automatically run once a new release is
-created and should publish the package to PyPi
+and create a Github release with a new tag, your GitHub workflow should automatically run once a new release is
+created and should publish the package to PyPi.
 
 Add to Django Packages
 ======================

cookiecutter-django-app/cookiecutter.json

@@ -9,9 +9,21 @@
   "author_name": "Open edX Project",
   "author_email": "[email protected]",
   "open_source_license": ["AGPL 3.0", "Apache Software License 2.0", "Not open source"],
-  "models": "Comma-separated list of models",
+  "models": "No Model",
   "config_class_name": "{{ cookiecutter.app_name|replace('_', ' ')|title|replace(' ', '') }}Config",
-  "_copy_without_render": [
-    ".github/workflows/*.yml"
-  ]
+  "_copy_without_render": [".github/workflows/*.yml"],
+  "__prompts__": {
+    "github_org": "GitHub organization",
+    "repo_name": "Repository name",
+    "app_name": "Application name",
+    "project_name": "Project name",
+    "project_title": "Project title",
+    "project_short_description": "Short description of the project",
+    "version": "Version",
+    "author_name": "Author's name",
+    "author_email": "Author's email",
+    "open_source_license": "Package license",
+    "models": "Comma-separated list of models",
+    "config_class_name": "Configuration class name"
+  }
 }

cookiecutter-django-app/{{cookiecutter.repo_name}}/requirements/base.in

@@ -2,7 +2,7 @@
 -c constraints.txt
 
 Django             # Web application framework
-{% if cookiecutter.models != "Comma-separated list of models" -%}
+{% if cookiecutter.models != "No Model" -%}
 django-model-utils        # Provides TimeStampedModel abstract base class
 {%- endif %}
 

cookiecutter-django-app/{{cookiecutter.repo_name}}/tests/test_models.py

@@ -4,7 +4,7 @@
 """
 
 import pytest
-{%- if cookiecutter.models != "Comma-separated list of models" -%}
+{%- if cookiecutter.models != "No Model" -%}
 {%- for model in cookiecutter.models.replace(' ', '').split(',') %}
 
 

cookiecutter-django-app/{{cookiecutter.repo_name}}/{{cookiecutter.app_name}}/models.py

@@ -1,7 +1,7 @@
 """
 Database models for {{cookiecutter.app_name}}.
 """
-{%- if cookiecutter.models != "Comma-separated list of models" %}
+{%- if cookiecutter.models != "No Model" %}
 # from django.db import models
 from model_utils.models import TimeStampedModel
 {%- for model in cookiecutter.models.replace(' ', '').split(',') %}

cookiecutter-django-ida/README.rst

@@ -1,7 +1,7 @@
 cookiecutter-django-ida
 #######################
 
-A cookiecutter_ template for edX Django projects.
+A cookiecutter_ template for Open edX Django projects.
 
 .. _cookiecutter: https://cookiecutter.readthedocs.org/en/latest/index.html
 
@@ -27,16 +27,14 @@ The necessary configuration is also in place to support:
 Usage
 *****
 
-
 To create a project using this cookiecutter, follow the instructions found in edx-cookiecutter's `readme`_.
 
 .. _readme: https://github.com/openedx/edx-cookiecutters/blob/master/README.rst
 
-
 After the new folder is created, you will need to:
 
 1. ``cd <new_repo_folder>``
-2. Create a python 3 virtual environment and activate it
+2. Create a Python 3 virtual environment and activate it
 3. ``make upgrade``
 4. ``make docker_build``
 5. ``docker-compose up``
@@ -69,7 +67,7 @@ The project includes a custom Django user model in ``core/models.py``. You must
 
 .. code-block:: bash
 
-    $ python manage.py makemigrations
+    python manage.py makemigrations
 
 Documentation
 =============
@@ -86,16 +84,16 @@ Contributions are welcome. Please read `How To Contribute <https://github.com/op
 Testing
 =======
 
-The ``Makefile`` includes a ``test`` target that runs basic validation on this template. This validation includes::
+The ``Makefile`` includes a ``test`` target that runs basic validation on this template. This validation includes:
 
-    * Create a new project using the template.
-    * Generate and install pinned requirements
-    * Run the project's migrations and validations.
-    * Extract and compile translations.
-    * Compile documentation.
+* Create a new project using the template.
+* Generate and install pinned requirements
+* Run the project's migrations and validations.
+* Extract and compile translations.
+* Compile documentation.
 
 Run this validation using the command below.
 
 .. code-block:: bash
 
-    $ make test
+    make test