Implement PoC of Makefile target documentation pattern

Makefile

@@ -33,8 +33,22 @@ help: status
 	@echo "Please excuse the currently verbose logging mode"
 	@echo "make help -- show this help"
 	@echo ""
-
-cookiecutter-help: status
+	@#
+	@# Display a list of documented targets.
+	@#
+	@# Note: This `@sed` command finds all the Makefile lines that contain a target name, a colon, and the
+	@#       made-up token — `#//` — and prints the target name and the post-token text to the console.
+	@#       You can use the `cookiecutter-help` target below as an example.
+	@#
+	@#                                ↓ skip                      ↓ token           ↙  ↘ ANSI escape codes (for color)
+	@#                                -------                     -----      --------  -------
+	@sed --silent --regexp-extended '/@sed/!s/^([^[:space:]]+?):.*#\/\/ (.*)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) | sort
+	@#                                          --------------  --       --  ---------------------    ----------------
+	@#                                   target ↑               ↑ deps   ↑ docs   ↑ output            ↑ all Makefiles
+	@#
+	@# Reference: https://stackoverflow.com/questions/8889035/how-to-document-a-makefile/47107132
+
+cookiecutter-help: status  #// Show targets inherited from cookiecutter
 	@echo ""
 	@echo "make setup -- initial setup (run this first)"
 	@echo "make site -- makes site locally"
@@ -47,7 +61,7 @@ cookiecutter-help: status
 	@echo "make cookiecutter-help -- show this help"
 	@echo ""
 
-status: check-config
+status: check-config  #// Show project metadata
 	@echo "Project: $(SCHEMA_NAME)"
 	@echo "Source: $(SOURCE_SCHEMA_PATH)"
 
@@ -148,7 +162,7 @@ check-config:
 	@(grep my-datamodel about.yaml > /dev/null && printf "\n**Project not configured**:\n\n - Remember to edit 'about.yaml'\n\n" || exit 0)
 
 # Test documentation locally
-serve: mkd-serve
+serve: mkd-serve  #// Run Mkdocs web server (alias for "mkdocs serve" command)
 
 # Python datamodel
 $(PYMODEL):
@@ -157,15 +171,15 @@ $(PYMODEL):
 $(DOCDIR):
 	mkdir -p $@
 
-gendoc: $(DOCDIR)
+gendoc: $(DOCDIR)  #// Convert schema content into Markdown files in "docs" folder
 	# added copying of images and renaming of TEMP.md
 	cp $(SRC)/docs/*md $(DOCDIR) ; \
 	cp -r $(SRC)/docs/images $(DOCDIR) ; \
 	$(RUN) gen-doc -d $(DOCDIR) --template-directory $(SRC)/$(TEMPLATEDIR) $(SOURCE_SCHEMA_PATH)
 	mkdir -p $(DOCDIR)/javascripts
 	$(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/
 
-testdoc: gendoc serve
+testdoc: gendoc serve  #// Generate Markdown files, convert them into HTML, and serve them
 
 MKDOCS = $(RUN) mkdocs
 mkd-%:
@@ -215,7 +229,8 @@ git-status:
 	echo "creating a stub for .cruft.json. IMPORTANT: setup via cruft not cookiecutter recommended!" ; \
 	touch $@
 
-clean:
+# TODO: Consider removing `rm -rf docs/*.html` since HTML files go to "site/", not "docs/".
+clean:  #// Delete project directory, temporary build artifacts, and generated doc files
 	rm -rf $(DEST)
 	rm -rf tmp
 	rm -rf docs/*.md

project.Makefile

@@ -270,14 +270,14 @@ local/mongo_as_nmdc_database_cuire_repaired.ttl: local/mongo_as_nmdc_database.tt
 .PHONY: migration-doctests migrator
 
 # Runs all doctests defined within the migrator modules, adapters, and CLI scripts.
-migration-doctests:
+migration-doctests:  #// Run migration-related doctests
 	$(RUN) python -m doctest -v nmdc_schema/migrators/*.py
 	$(RUN) python -m doctest -v nmdc_schema/migrators/adapters/*.py
 	$(RUN) python -m doctest -v nmdc_schema/migrators/cli/*.py
 
 # Generates a migrator skeleton for the specified schema versions.
 # Note: `create-migrator` is a Poetry script registered in `pyproject.toml`.
-migrator:
+migrator:  #// Generate a migrator interactively
 	$(RUN) create-migrator
 
 .PHONY: filtered-status