From bfdcf31438a8fd8df440fec0d288e7183469747a Mon Sep 17 00:00:00 2001
From: Marien Fressinaud <dev@marienfressinaud.fr>
Date: Mon, 3 Sep 2018 20:28:46 +0200
Subject: doc: Improve Makefile (#387)

* Add help target to the Makefile

It is often expected to have a `help` target in a Makefile. This one is
automatically generated from comments in the Makefile so it is easier to
maintain.

This commit only documents targets that seem the most important.

* Add the server address and port on `make serve`

Developers should not have to read the documentation to find where to
point their browsers to access ihatemoney application.

* Add .PHONY instructions to the Makefile

`.PHONY` instructs Make to not look, for instance, for an `install` file
before executing the corresponding target. If such a file would exist,
the command would not be performed at all. This is because Make is
initially intended to create files (i.e. targets) and consider there is
nothing to do if the file already exists.

More information on https://stackoverflow.com/a/2145605.
---
 Makefile | 43 +++++++++++++++++++++++++++++++------------
 1 file changed, 31 insertions(+), 12 deletions(-)

diff --git a/Makefile b/Makefile
index e273b80..8c48ed4 100644
--- a/Makefile
+++ b/Makefile
@@ -7,52 +7,71 @@ DOC_STAMP = $(VENV)/.doc_env_installed.stamp
 INSTALL_STAMP = $(VENV)/.install.stamp
 TEMPDIR := $(shell mktemp -d)
 
-all: install
-install: virtualenv $(INSTALL_STAMP)
+.PHONY: all
+all: install ## Alias for install
+.PHONY: install
+install: virtualenv $(INSTALL_STAMP) ## Install dependencies
 $(INSTALL_STAMP):
 	$(VENV)/bin/pip install -U pip
 	$(VENV)/bin/pip install -r requirements.txt
 	touch $(INSTALL_STAMP)
 
+.PHONY: virtualenv
 virtualenv: $(PYTHON)
 $(PYTHON):
 	$(VIRTUALENV) $(VENV)
 
-install-dev: $(INSTALL_STAMP) $(DEV_STAMP)
+.PHONY: install-dev
+install-dev: $(INSTALL_STAMP) $(DEV_STAMP) ## Install development dependencies
 $(DEV_STAMP): $(PYTHON) dev-requirements.txt
 	$(VENV)/bin/pip install -Ur dev-requirements.txt
 	touch $(DEV_STAMP)
 
+.PHONY: remove-install-stamp
 remove-install-stamp:
 	rm $(INSTALL_STAMP)
 
-update: remove-install-stamp install
+.PHONY: update
+update: remove-install-stamp install ## Update the dependencies
 
-serve: install
+.PHONY: serve
+serve: install ## Run the ihatemoney server
+	@echo 'Running ihatemoney on http://localhost:5000'
 	$(PYTHON) -m ihatemoney.manage runserver
 
-test: $(DEV_STAMP)
+.PHONY: test
+test: $(DEV_STAMP) ## Run the tests
 	$(VENV)/bin/tox
 
-release: $(DEV_STAMP)
+.PHONY: release
+release: $(DEV_STAMP) ## Release a new version (see https://ihatemoney.readthedocs.io/en/latest/contributing.html#how-to-release)
 	$(VENV)/bin/fullrelease
 
-build-translations:
+.PHONY: build-translations
+build-translations: ## Build the translations
 	$(VENV)/bin/pybabel compile -d ihatemoney/translations
 
-update-translations:
+.PHONY: update-translations
+update-translations: ## Extract new translations from source code
 	$(VENV)/bin/pybabel extract --strip-comments --omit-header --no-location --mapping-file ihatemoney/babel.cfg -o ihatemoney/messages.pot ihatemoney
 	$(VENV)/bin/pybabel update -i ihatemoney/messages.pot -d ihatemoney/translations/
 
-create-database-revision:
+.PHONY: create-database-revision
+create-database-revision: ## Create a new database revision
 	@read -p "Please enter a message describing this revision: " rev_message; \
 	$(PYTHON) -m ihatemoney.manage db migrate -d ihatemoney/migrations -m "$${rev_message}"
 
-build-requirements:
+.PHONY: build-requirements
+build-requirements: ## Save currently installed packages to requirements.txt
 	$(VIRTUALENV) $(TEMPDIR)
 	$(TEMPDIR)/bin/pip install -U pip
 	$(TEMPDIR)/bin/pip install -Ue "."
 	$(TEMPDIR)/bin/pip freeze | grep -v -- '-e' > requirements.txt
 
-clean:
+.PHONY: clean
+clean: ## Destroy the virtual environment
 	rm -rf .venv
+
+.PHONY: help
+help: ## Show the help indications
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
-- 
cgit v1.1