This pull request implements a documentation structure for the project's Makefile, based on this article. This structure is meant to be interactive via terminal and can be easily updated, even for lengthy Makefiles.
Why is the PR needed?
To facilitate the life of the developers, in the search for useful information concerning project manipulation.
What the PR does?
Implements a help task in the Makefile:
.DEFAULT_GOAL := help
help: ## Show helpful information concerning the available tasks
@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
.PHONY: help
that performs the parsing, via a regular expression, of the comments denoting the help information, starting with ##, that must be written in the same line of the task declaration, eg.:
fizz-buzz: ## This is the docstring. This task just prints "Fizz Buzz"
@echo 'Fizz Buzz'
.PHONY: fizz-buzz
What are possible side effects?
If the docstring is not specified under the established format, some scripts may stop working.
Checklist
[ ] At the project's root, run in the terminal make or make help. Either one should list the tasks and their respective docstrings, as illustrated below:
[ ] Run each task separately, to make sure that their execution was not impaired by the introduction of the docstring.
Description
This pull request implements a documentation structure for the project's Makefile, based on this article. This structure is meant to be interactive via terminal and can be easily updated, even for lengthy Makefiles.
Why is the PR needed?
To facilitate the life of the developers, in the search for useful information concerning project manipulation.
What the PR does?
Implements a
help
task in the Makefile:that performs the parsing, via a regular expression, of the comments denoting the help information, starting with
##
, that must be written in the same line of the task declaration, eg.:What are possible side effects?
If the docstring is not specified under the established format, some scripts may stop working.
Checklist
make
ormake help
. Either one should list the tasks and their respective docstrings, as illustrated below: