Today was my 6th day of 100 days of code. I was working on the forthcoming Two Scoops of Django 3.x and thanks to my co-worker Fabio I learned something new about Makefiles. This is an expansion on what he provided (I added the output list and sort feature).
I've seen variations of this trick but this is the best version ever. At the top of your
Makefile, put in this code:
.DEFAULT_GOAL := help # Sets default action to be help define PRINT_HELP_PYSCRIPT # start of Python section import re, sys output =  # Loop through the lines in this file for line in sys.stdin: # if the line has a command and a comment start with # two pound signs, add it to the output match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line) if match: target, help = match.groups() output.append("%-20s %s" % (target, help)) # Sort the output in alphanumeric order output.sort() # Print the help result print('\n'.join(output)) endef export PRINT_HELP_PYSCRIPT # End of python section help: @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
Next, we added concise docstrings for every
Makefile command. Here's what we did for two of the commands:
code: ## Extracts code for uploading to GitHub python extractor.py rmcode: ## Removes sample code rm -rf code
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 clean Cleans up the environment cleandocker Cleans up the docker environment code Extracts code for uploading to GitHub dpdf Render PDF in docker mdeps Discovers missing LaTeX deps mint Production ebook rendering print Renders print version rmcode Removes sample code short faster rendering with minimal index check tiny even faster rendering with no index check