Autodocumenting Makefiles

0
22
Autodocumenting Makefiles


A few years ago Fabio da Luz taught me some Makefile tricks. This is an expansion on what he taught me (I added the output list and sort feature).

At the top of your Makefile, put in this code:

.DEFAULT_GOAL := help 

define PRINT_HELP_PYSCRIPT 
import re, sys

output = []

for line in sys.stdin:
    
    
    match = re.match(r'^([a-zA-Z_-]+):.*?
    if match:
        target, help = match.groups()
        output.append("%-10s %s" % (target, help))

output.sort()

print('n'.join(output))
endef
export PRINT_HELP_PYSCRIPT 

help:
    @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)

Next, add concise docstrings for every Makefile command. Here’s a trio of examples:

env:  ## Activate the virtual environment
	source venv/bin/activate

test: ## Runs the test suite 
	python manage.py test --thing=stuff

run:  ## Start the dev server
	python manage.py runserver    

Notice how each command’s docstring starts with two pound signs? The “##”? That’s what the auto documenter code needs to find the docstring.

When I type just make without any arguments, by default that triggers the help function, which runs the Python script at the top of the makefile. What I get is this:

$ make
env             Activate the virtual environment
run             Start the dev server
test            Runs the test suite 

The results have been alphabetized, with comments displayed for each command. Very useful!

.DEFAULT_GOAL := help 

define PRINT_HELP_PYSCRIPT 
import re, sys

output = []

for line in sys.stdin:
    
    
    match = re.match(r'^([a-zA-Z_-]+):.*?
    if match:
        target, help = match.groups()
        output.append("%-10s %s" % (target, help))

output.sort()

print('n'.join(output))
endef
export PRINT_HELP_PYSCRIPT 

help:
	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)

env:  ## Activate the virtual environment
	source venv/bin/activate

test: ## Runs the test suite 
	python manage.py test --thing=stuff

run:  ## Start the dev server
	python manage.py runserver    

Autodocumenting Makefiles





Source link

Leave a reply

Please enter your comment!
Please enter your name here