refactor, fix, and document Justfile commands (#94)

Author: joshuadavidthomas

CHANGELOG.md

@@ -23,11 +23,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 -   Now prompted for the version of PostGIS to use in the project, if `postgis/postgis` is chosen as the PostgreSQL database.
 -   A new example project has been added to the `examples` directory using PostGIS.
+-   Two new `Justfile` commands for using `copier`'s recopy command: `copier-recopy` and `copier-recopy-all`.
+-   All `Justfile` commands now have a short description that is displayed when running `just` (default command) or `just --list`.
 
 ### Changed
 
 -   PostgreSQL version now takes into account the version of PostGIS, if that option is chosen.
 
+### Fixed
+
+-   Removed extra `test` command in `Justfile`.
+-   Fixed `compose.yml` filename in various `Justfile` commands.
+
 ## [2024.9]
 
 ### Changed

src/django_twc_project/Justfile.jinja

@@ -2,29 +2,36 @@ set dotenv-load := true
 
 export DATABASE_URL := env_var_or_default('DATABASE_URL', '{{ postgres_uri_scheme }}://postgres:postgres@db:5432/postgres')
 
+# List all available commands
 @_default:
     just --list
 
 # ----------------------------------------------------------------------
 # DEPENDENCIES
 # ----------------------------------------------------------------------
 
+# Bootstrap local development environment
 bootstrap:
-    python -m pip install --upgrade pip uv
+    @just pup
     @just install
 
+# Generate requirements file
 lock *ARGS:
     python -m uv pip compile {% raw %}{{ ARGS }}{% endraw %} --generate-hashes requirements.in --output-file requirements.txt
 
+# Install dependencies
 install *ARGS:
     python -m uv pip install --upgrade -r requirements.txt
 
+# Generate and upgrade dependencies
 upgrade:
     @just lock --upgrade
 
+# Install and update dependency tools
 pup:
     python -m pip install --upgrade pip uv
 
+# Update local development environment
 update:
     @just pup
     @just upgrade
@@ -62,55 +69,66 @@ coverage:
     docker compose run --rm --no-deps -e PWDEBUG=1 app pytest {% raw %}{{ ARGS }}{% endraw %}
 {%- endif %}
 
+# Run mypy on project
 types:
     just command python -m mypy .
 
 # ----------------------------------------------------------------------
 # DJANGO
 # ----------------------------------------------------------------------
 
+# Run a Django management command
 @manage *COMMAND:
     just command python -m manage {% raw %}{{ COMMAND }}{% endraw %}
 
+# Alias for makemigrations
 alias mm := makemigrations
 
+# Generate Django migrations
 makemigrations *APPS:
     @just manage makemigrations {% raw %}{{ APPS }}{% endraw %}
 
+# Run Django migrations
 migrate *ARGS:
     @just manage migrate {% raw %}{{ ARGS }}{% endraw %}
 
+# Open a Django shell using django-extensions shell_plus command
 shell-plus:
     @just manage shell_plus
 
+# Quickly create a superuser with the provided credentials
 createsuperuser USERNAME="admin" EMAIL="" PASSWORD="admin":
     docker compose run --rm --no-deps app /bin/bash -c 'echo "from django.contrib.auth import get_user_model; User = get_user_model(); User.objects.create_superuser('"'"'{% raw %}{{ USERNAME }}{% endraw %}'"'"', '"'"'{% raw %}{{ EMAIL }}{% endraw %}'"'"', '"'"'{% raw %}{{ PASSWORD }}{% endraw %}'"'"') if not User.objects.filter(username='"'"'{% raw %}{{ USERNAME }}{% endraw %}'"'"').exists() else None" | python manage.py shell'
 
+# Reset a user's password
 resetuserpassword USERNAME="admin" PASSWORD="admin":
     docker compose run --rm --no-deps app /bin/bash -c 'echo "from django.contrib.auth import get_user_model; User = get_user_model(); user = User.objects.get(username='"'"'{% raw %}{{ USERNAME }}{% endraw %}'"'"'); user.set_password('"'"'{% raw %}{{ PASSWORD }}{% endraw %}'"'"'); user.save()" | python manage.py shell'
 
-# ----------------------------------------------------------------------
-# DOCS
-# ----------------------------------------------------------------------
-
-_cog:
-    cog -r docs/just.md
-
+# Graph models using django-extensions graph_models command
 graph:
     just manage graph_models users \
         --exclude-models AbstractUser \
         --group-models \
         --output ./docs/applications/images/users.svg
 
-docs-lock *ARGS:
-    python -m uv pip compile {% raw %}{{ ARGS }}{% endraw %} --generate-hashes docs/requirements.in --output-file docs/requirements.txt
+# ----------------------------------------------------------------------
+# DOCS
+# ----------------------------------------------------------------------
 
-docs-upgrade:
-    @just docs-lock --upgrade
+# Build documentation using Sphinx
+docs-build LOCATION="docs/_build/html":
+    just _cog
+    sphinx-build docs {% raw %}{{ LOCATION }}{% endraw %}
 
+# Install documentation dependencies
 docs-install:
     python -m uv pip install --upgrade -r docs/requirements.txt
 
+# Generate documentation requirements
+docs-lock *ARGS:
+    python -m uv pip compile {% raw %}{{ ARGS }}{% endraw %} --generate-hashes docs/requirements.in --output-file docs/requirements.txt
+
+# Serve documentation locally
 docs-serve:
     #!/usr/bin/env sh
     just _cog
@@ -120,21 +138,24 @@ docs-serve:
         sphinx-autobuild docs docs/_build/html --host "localhost"
     fi
 
-docs-build LOCATION="docs/_build/html":
-    just _cog
-    sphinx-build docs {% raw %}{{ LOCATION }}{% endraw %}
+# Generate and upgrade documentation dependencies
+docs-upgrade:
+    @just docs-lock --upgrade
+
+_cog:
+    cog -r docs/just.md
 
 # ----------------------------------------------------------------------
 # DOCKER
 # ----------------------------------------------------------------------
 
-# Build services using docker-compose
+# Build services using docker compose
 build *ARGS:
     docker compose build {% raw %}{{ ARGS }}{% endraw %}
 
-# Build production stack using docker-compose
+# Build production stack using docker compose
 build-prod:
-    docker compose -f docker-compose.yml -f docker-compose.prod.yml build
+    docker compose -f compose.yml -f compose.prod.yml build
 
 # Stop and remove all containers, networks, images, and volumes
 clean:
@@ -148,7 +169,7 @@ command *ARGS:
 console:
     docker compose run --rm --no-deps app /bin/bash
 
-# Stop and remove all containers defined in docker-compose
+# Stop and remove all containers defined in docker compose
 down *ARGS:
     docker compose down {% raw %}{{ ARGS }}{% endraw %}
 
@@ -160,7 +181,7 @@ logs *ARGS:
 ps:
     docker compose ps
 
-# Pull the latest versions of all images defined in docker-compose
+# Pull the latest versions of all images defined in docker compose
 pull:
     docker compose pull
 
@@ -176,11 +197,11 @@ shell *ARGS="app":
 shell-db:
     docker compose run --rm --no-deps db psql -d {% raw %}{{ DATABASE_URL }}{% endraw %}
 
-# Start services using docker-compose, defaulting to detached mode
+# Start services using docker compose, defaulting to detached mode
 start *ARGS="--detach":
     @just up {% raw %}{{ ARGS }}{% endraw %}
 
-# Start the full production stack using docker-compose, defaulting to detached mode
+# Start the full production stack using docker compose, defaulting to detached mode
 start-prod *ARGS="--detach":
     @just up-prod {% raw %}{{ ARGS }}{% endraw %}
 
@@ -192,20 +213,20 @@ stop:
 tail *ARGS:
     @just logs '--follow {% raw %}{{ ARGS }}{% endraw %}'
 
-# Start services using docker-compose, with optional arguments
+# Start services using docker compose, with optional arguments
 up *ARGS:
     docker compose up {% raw %}{{ ARGS }}{% endraw %}
 
-# Start the full production stack using docker-compose
+# Start the full production stack using docker compose
 up-prod *ARGS:
-    docker compose -f docker-compose.yml -f docker-compose.prod.yml up {% raw %}{{ ARGS }}{% endraw %}
+    docker compose -f compose.yml -f compose.prod.yml up {% raw %}{{ ARGS }}{% endraw %}
 
 
 # ----------------------------------------------------------------------
 # POSTGRES BACKUP AND RESTORE
 # ----------------------------------------------------------------------
 
-# dump our local database to file
+# Dump our local database to file
 pg_dump database_url=DATABASE_URL file='db.dump':
     docker compose run \
         --rm \
@@ -217,12 +238,12 @@ pg_dump database_url=DATABASE_URL file='db.dump':
             --format=c \
             --verbose
 
-# dump our production database to file
+# Dump our production database to file
 pg_dump_prod file='production.dump':
     set PROD_DATABASE_URL := "{% raw %}{{ env_var('PROD_DATABASE_URL') }}{% endraw %}"
     @just pg_dump ${PROD_DATABASE_URL} {% raw %}{{ file }}{% endraw %}
 
-# restore database backup to our local database
+# Restore database backup to our local database
 pg_restore file='db.dump':
     docker compose run \
         --rm \
@@ -240,6 +261,7 @@ pg_restore file='db.dump':
 # UTILS
 # ----------------------------------------------------------------------
 
+# Sync .env* files
 envsync:
     #!/usr/bin/env python
     from pathlib import Path
@@ -257,26 +279,34 @@ envsync:
         lines.sort()
         envfile_example.write_text(''.join(lines))
 
-# format justfile
+# Format justfile
 fmt:
     just --fmt --unstable
 
-# run pre-commit on all files
+# Run pre-commit on all files
 lint:
     pre-commit run --all-files
 
 # ----------------------------------------------------------------------
 # COPIER
 # ----------------------------------------------------------------------
 
-# create a copier answers file
+# Create a copier answers file
 copier-copy TEMPLATE_PATH DESTINATION_PATH=".":
-    pipx run copier copy {% raw %}{{ TEMPLATE_PATH }}{% endraw %} {% raw %}{{ DESTINATION_PATH }}{% endraw %}
+    python -m copier copy --trust {% raw %}{{ TEMPLATE_PATH }}{% endraw %} {% raw %}{{ DESTINATION_PATH }}{% endraw %}
+
+# Recopy the project from the original template
+copier-recopy ANSWER_FILE *ARGS:
+    python -m copier recopy --trust --answers-file {% raw %}{{ ANSWERS_FILE }}{% endraw %} {% raw %}{{ ARGS }}{% endraw %}
+
+# Loop through all answers files and recopy the project using copier
+@copier-recopy-all *ARGS:
+    for file in `ls .copier/`; do just copier-recopy .copier/$file "{% raw %}{{ ARGS }}{% endraw %}"; done
 
-# update the project using a copier answers file
+# Update the project using a copier answers file
 copier-update ANSWERS_FILE *ARGS:
-    pipx run copier update --answers-file {% raw %}{{ ANSWERS_FILE }}{% endraw %} {% raw %}{{ ARGS }}{% endraw %}
+    python -m copier update --trust --answers-file {% raw %}{{ ANSWERS_FILE }}{% endraw %} {% raw %}{{ ARGS }}{% endraw %}
 
-# loop through all answers files and update the project using copier
+# Loop through all answers files and update the project using copier
 @copier-update-all *ARGS:
-    for file in `ls .copier-answers/`; do just copier-update .copier-answers/$file "{% raw %}{{ ARGS }}{% endraw %}"; done
+    for file in `ls .copier/`; do just copier-update .copier/$file "{% raw %}{{ ARGS }}{% endraw %}"; done