Improve Makefile

Signed-off-by: Pedro B S Lisboa <[email protected]>

Author: pedrobslisboa

Makefile

@@ -1,42 +1,77 @@
+# Define installation arguments with optional prefix
 INSTALL_ARGS := $(if $(PREFIX),--prefix $(PREFIX),)
+# Define examples with their descriptions
+EXAMPLE_DESCRIPTIONS := \
+	"example-building-ast:Demonstrates how to build AST" \
+	"example-destructuring-ast:Demonstrates how to destructure an AST" \
 
-# Default rule
-default:
+.PHONY: help
+help: ## Print this help message
+	@echo "";
+	@echo "List of available make commands";
+	@echo "";
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}';
+	@echo "";
+	@echo "Available examples:";
+	@echo "";
+	@for desc in $(EXAMPLE_DESCRIPTIONS); do \
+		target=$$(echo $$desc | cut -d: -f1); \
+		description=$$(echo $$desc | cut -d: -f2); \
+		printf "  \033[36m%-30s\033[0m %s\n" "$$target" "$$description"; \
+	done
+	@echo "";
+
+.PHONY: default
+default: ## Build the project with auto-promote
 	dune build --auto-promote @install
 
-install:
+.PHONY: install
+install: ## Install the project
 	dune install $(INSTALL_ARGS)
 
-uninstall:
+.PHONY: uninstall
+uninstall: ## Uninstall the project
 	dune uninstall $(INSTALL_ARGS)
 
-reinstall: uninstall reinstall
+.PHONY: reinstall
+reinstall: ## Reinstall the project
+	uninstall reinstall
 
-test:
+.PHONY: test
+test: ## Run tests
 	dune runtest
 
-doc:
+.PHONY: doc
+doc: ## Build documentation
 	dune build @doc
 
-clean:
+.PHONY: doc-dev
+doc-dev: ## Build and watch documentation
+	dune build @doc --watch & dune_pid=$$!; \
+	trap 'kill $$dune_pid' EXIT; \
+	sleep 2 && open _build/default/_doc/_html/index.html & \
+	wait $$dune_pid
+
+.PHONY: clean
+clean: ## Clean the build artifacts
 	dune clean
 
-all-supported-ocaml-versions:
+.PHONY: all-supported-ocaml-versions
+all-supported-ocaml-versions: ## Build for all supported OCaml versions
 	dune build @install --workspace dune-workspace.dev --root .
 
-opam-release:
+.PHONY: opam-release
+opam-release: ## Release the project using opam
 	dune-release distrib --skip-build --skip-lint --skip-tests
 	dune-release publish distrib --verbose
 	dune-release opam pkg
 	dune-release opam submit
 
-bench:
+.PHONY: bench
+bench: ## Run benchmarks
 	dune build bench --profile release
 	dune exec bench/bench.exe
 
-.PHONY: default install uninstall reinstall clean test doc bench
-.PHONY: all-supported-ocaml-versions opam-release
-
 .PHONY: $(TARGET)
-example-%: 
-	DUNE_CONFIG__GLOBAL_LOCK=disabled opam exec -- dune exec $*-example
+example-%: ## Run example with specified target, e.g. make example-global-transformation
+	opam exec -- dune exec $*-example

doc/dune

@@ -1,13 +1,2 @@
 (documentation
  (package ppxlib))
-
-(rule
- (alias doc)
- (deps
-  (glob_files ./images/*))
- (action
-  (progn
-   (system "mkdir -p %{project_root}/_doc/_html/ppxlib/assets/images")
-   (system "chmod -R a+rw %{project_root}/_doc/_html/ppxlib/assets/images")
-   (system
-    "cp -R ./images/ %{project_root}/_doc/_html/ppxlib/assets/images/"))))

doc/example-ast.mld

@@ -291,7 +291,7 @@ As the AST represents the structure of the source code in a tree-like format, it
 I know that it can be a lot, but don't worry; we are going step by step, and you are going to understand it.
 
 {1 Samples} 
-To help you understand a little bit more about the AST, let's show it with some highlighted examples:
+To help you understand a little bit more about the AST, let's show it with some examples with the {{:https://astexplorer.net/} AST Explorer}:
 
 {table
   {tr