Self-Documented Makefile

[lgatto]

For the record: Self-Documented Makefile

[sgibb]

Or using just make itself: http://www.cmcrossroads.com/print/article/self-documenting-makefiles

[sgibb]

While I like the pure make approach by John Graham-Cumming we have already a dependency to sed etc. That's why I am thinking we could using sed and adding some sugar. What do you think about a syntax similar to roxygen2:

# stupid example Makefile
help:
    @sed -n "s/^#' *@section \(.*\)$$/\n\1:\n/p; \
             s/^#' *@param \([^ ]*\) \+\(.*\)\$$/ \1\t\2/p; \
             s/^\([^:]\+\):.*#' \([^@]\+\)\$$/ \1\t\2/p" $(MAKEFILE_LIST) | expand -t 30

#' @section CHECK TARGETS
check: #' check everything
    @echo checking

#' @section BUILD TARGETS
build: check build-without-check #' normal build

build-without-check: #' build without additional checks
    @echo building

#' @section ENVIRONMENT VARIABLES
#' @param PKG/PKGDIR path to the target package (default is 'maker')
#' @param MAKERRC path to the maker configuration file (default is '~/.makerrc')

❯ make help

CHECK TARGETS:

 check                        check everything

BUILD TARGETS:

 build                        normal build
 build-without-check          build without additional checks

ENVIRONMENT VARIABLES:

 PKG/PKGDIR                   path to the target package (default is 'maker')
 MAKERRC                      path to the maker configuration file (default is '~/.makerrc')

[lgatto]

I like it! And sed is so ubiquitous that it hardly counts as a dependency ;-)

[sgibb]

Now the make help output is very long but hopefully easier to maintain and the structure is better than before.

[lgatto]

I think it's great, thank you!