Document Makefile

Merge pull request #1036 from openfisca/doc-make

Author: Mauko Quiroga

.circleci/config.yml

@@ -20,7 +20,7 @@ jobs:
       - run:
           name: Install dependencies
           command: |
-            make install
+            make install.build
             # pip install --editable git+https://github.com/openfisca/country-template.git@BRANCH_NAME#egg=OpenFisca-Country-Template  # use a specific branch of OpenFisca-Country-Template
             # pip install --editable git+https://github.com/openfisca/extension-template.git@BRANCH_NAME#egg=OpenFisca-Extension-Template  # use a specific branch of OpenFisca-Extension-Template
 
@@ -107,7 +107,7 @@ jobs:
           name: Upload a Python package to Pypi
           command: |
             source /tmp/venv/openfisca_core/bin/activate
-            .circleci/publish-python-package.sh
+            twine upload dist/* --username $PYPI_USERNAME --password $PYPI_PASSWORD
 
       - run:
           name: Publish a git tag

.circleci/publish-python-package.sh

@@ -1,34 +1,49 @@
-all: test
+doc = sed -n "/^$1/ { x ; p ; } ; s/\#\#/[⚙]/ ; s/\./.../ ; x" ${MAKEFILE_LIST}
 
-uninstall:
-	pip freeze | grep -v "^-e" | xargs pip uninstall -y
+## Same as `make test`.
+all: test
 
+## Install project dependencies.
 install:
-	pip install --upgrade pip twine wheel
-	pip install --editable .[dev] --upgrade --use-deprecated=legacy-resolver
-
-clean:
-	rm -rf build dist
-	find . -name '*.pyc' -exec rm \{\} \;
-
-check-syntax-errors:
-	python -m compileall -q .
-
-check-types:
-	mypy openfisca_core && mypy openfisca_web_api
-
-check-style:
-	@# Do not analyse .gitignored files.
-	@# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764.
-	flake8 `git ls-files | grep "\.py$$"`
-
-format-style:
-	@# Do not analyse .gitignored files.
-	@# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764.
-	autopep8 `git ls-files | grep "\.py$$"`
+	@$(call doc,$@:)
+	@pip install --upgrade pip setuptools wheel
+	@pip install --editable .[dev] --upgrade --use-deprecated=legacy-resolver
 
+## Recreate a clean slate locally.
+uninstall:
+	@## Trying out packages, building openfisca, etc., can make tests fail.
+	@## This task uninstalls everything, including packages in editable mode.
+	@$(call doc,$@:)
+	pip freeze | grep -v "^-e" | sed "s/@.*//" | xargs pip uninstall -y
+
+## Delete builds and compiled python files.
+clean: \
+	$(shell ls -d * | grep "build\|dist") \
+	$(shell find . -name "*.pyc")
+	@$(call doc,$@:)
+	@rm -rf $?
+
+## Run linters to check for syntax and style errors.
+check-style: $(shell git ls-files "*.py")
+	@$(call doc,$@:)
+	@flake8 $?
+
+## Run code formatters to correct style errors.
+format-style: $(shell git ls-files "*.py")
+	@$(call doc,$@:)
+	@autopep8 $?
+
+## Run static type checkers for type errors.
+check-types: openfisca_core openfisca_web_api
+	@$(call doc,$@:)
+	@mypy $?
+
+## Run openfisca-core tests.
 test: clean check-syntax-errors check-style check-types
-	env PYTEST_ADDOPTS="$$PYTEST_ADDOPTS --cov=openfisca_core" pytest
+	@$(call doc,$@:)
+	@PYTEST_ADDOPTS="${PYTEST_ADDOPTS} --cov=openfisca_core" pytest
 
+## Serve the openfisca Web API.
 api:
-	openfisca serve --country-package openfisca_country_template --extensions openfisca_extension_template
+	@$(call doc,$@:)
+	@openfisca serve --country-package openfisca_country_template --extensions openfisca_extension_template