From 8d4d4e04717b19e232e6aae2e094f22e0ba011f8 Mon Sep 17 00:00:00 2001
From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com>
Date: Sat, 5 Oct 2024 20:15:28 +0100
Subject: [PATCH] Document Just Commands

---
 Justfile | 73 +++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 49 insertions(+), 24 deletions(-)

diff --git a/Justfile b/Justfile
index 84c694d..ba30519 100644
--- a/Justfile
+++ b/Justfile
@@ -1,7 +1,36 @@
 # ------------------------------------------------------------------------------
-# General Commands
+# Common Commands
 # ------------------------------------------------------------------------------
 
+# Install python dependencies
+install:
+    poetry install
+
+# Run the analyser
+run:
+    poetry run python -m analyser
+
+# Run the analyser with default values
+run-with-defaults:
+    DEBUG=true INPUT_REPOSITORY_OWNER=JackPlowman poetry run python -m analyser
+
+# Run unit tests
+unit-test:
+    poetry run pytest analyser --cov=. --cov-report=xml
+
+# Run unit tests with debug output
+unit-test-debug:
+    poetry run pytest analyser --cov=. --cov-report=xml -vvvv
+
+# Validate the schema of the generated statistics file
+validate-schema:
+    poetry run check-jsonschema --schemafile test/schema_validation/repository_statistics_schema.json test/schema_validation/repository_statistics.json
+
+# ------------------------------------------------------------------------------
+# Cleaning Commands
+# ------------------------------------------------------------------------------
+
+# Remove all cloned repositories and generated files
 clean:
     just clean-repos
     just clean-generated-files
@@ -18,38 +47,23 @@ clean:
       -name 'db.sqlite3' \
     \) -print | xargs rm -rfv
 
+# Remove all cloned repositories
 clean-repos:
     rm -rf cloned_repositories/** || true
 
+# Remove all generated files from running analyser
 clean-generated-files:
     rm statistics/*.csv || true
 
-install:
-    poetry install
-
-run:
-    poetry run python -m analyser
-
-run-with-defaults:
-    DEBUG=true INPUT_REPOSITORY_OWNER=JackPlowman poetry run python -m analyser
-
-unit-test:
-    poetry run pytest analyser --cov=. --cov-report=xml
-
-unit-test-debug:
-    poetry run pytest analyser --cov=. --cov-report=xml -vvvv
-
-validate-schema:
-    poetry run check-jsonschema --schemafile test/schema_validation/repository_statistics_schema.json test/schema_validation/repository_statistics.json
-
 # ------------------------------------------------------------------------------
-# Docker
+# Docker Commands
 # ------------------------------------------------------------------------------
 
 # Build the Docker image
 docker-build:
     docker build -t jackplowman/github-stats-analyser:latest .
 
+# Run the analyser in a Docker container, used for testing the github action docker image
 docker-run:
     docker run \
       --env github_token=${GITHUB_TOKEN} \
@@ -60,25 +74,31 @@ docker-run:
       --rm jackplowman/github-stats-analyser:latest
 
 # ------------------------------------------------------------------------------
-# Ruff - Set up red-knot when it's ready
+# Ruff - Python Linting and Formating
+# Set up ruff red-knot when it's ready
 # ------------------------------------------------------------------------------
 
+# Fix all Ruff issues
 ruff-fix:
-    just analyser::ruff-lint-fix
-    just analyser::ruff-format-fix
+    just ruff-lint-fix
+    just ruff-format-fix
 
+# Check for Ruff issues
 ruff-lint:
     poetry run ruff check analyser
     poetry run ruff check python_scripts
 
+# Fix Ruff lint issues
 ruff-lint-fix:
     poetry run ruff check analyser --fix
     poetry run ruff check python_scripts --fix
 
+# Check for Ruff format issues
 ruff-format:
     poetry run ruff format --check analyser
     poetry run ruff format --check python_scripts
 
+# Fix Ruff format issues
 ruff-format-fix:
     poetry run ruff format analyser
     poetry run ruff format python_scripts
@@ -87,16 +107,19 @@ ruff-format-fix:
 # Other Python Tools
 # ------------------------------------------------------------------------------
 
+# Check for unused code
 vulture:
     poetry run vulture analyser
 
 # ------------------------------------------------------------------------------
-# Prettier
+# Prettier - File Formatting
 # ------------------------------------------------------------------------------
 
+# Check for prettier issues
 prettier-check:
     prettier . --check
 
+# Fix prettier issues
 prettier-format:
     prettier . --check --write
 
@@ -104,9 +127,11 @@ prettier-format:
 # Justfile
 # ------------------------------------------------------------------------------
 
+# Format the Just code
 format:
     just --fmt --unstable
 
+# Check for Just format issues
 format-check:
     just --fmt --check --unstable