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).
Using PYSCRIPT to Print Documentation
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.
Trying it out!
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 Very useful!
Top comments (1)
I was looking for a good solution last week for this and gave up. This is the best! thanks.