From 64a979e6d432a22976d1af30c735ef40452e704b Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sun, 26 May 2024 00:51:54 -0700 Subject: [PATCH 01/11] Implement PoC of Makefile target documentation pattern --- Makefile | 20 +++++++++++++++++--- project.Makefile | 4 ++-- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index a596584642..ba70c5044c 100644 --- a/Makefile +++ b/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 (optional) and contain the + @# made-up token — `#//` — and prints the target name (if present) and the post-token text to the console. + @# You can use the `cookiecutter-help` target below as an example. + @# + @# ↓ skip ↓ token + @# ------- ----- + @sed -n -e '/@sed/!s/\(^.*:\)*.*#\/\/ \(.*\)/\1 \2/p' $(MAKEFILE_LIST) + @# -- -- -- ----- ---------------- + @# 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)" diff --git a/project.Makefile b/project.Makefile index 1f9a6f3a6f..aa89ebea6a 100644 --- a/project.Makefile +++ b/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 From 851daed983ee6b02cdb80eece91534a5f4329209 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sun, 26 May 2024 20:59:37 -0700 Subject: [PATCH 02/11] Display the target name in purple --- Makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index ba70c5044c..9750f479f4 100644 --- a/Makefile +++ b/Makefile @@ -40,11 +40,11 @@ help: status @# made-up token — `#//` — and prints the target name (if present) and the post-token text to the console. @# You can use the `cookiecutter-help` target below as an example. @# - @# ↓ skip ↓ token - @# ------- ----- - @sed -n -e '/@sed/!s/\(^.*:\)*.*#\/\/ \(.*\)/\1 \2/p' $(MAKEFILE_LIST) - @# -- -- -- ----- ---------------- - @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles + @# ↓ skip ↓ token ↙ ↘ ANSI escape codes (for color) + @# ------- ----- -------- ------- + @sed -n -e '/@sed/!s/\(^.*\)*:.*#\/\/ \(.*\)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) + @# -- -- -- --------------------- ---------------- + @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles @# @# Reference: https://stackoverflow.com/questions/8889035/how-to-document-a-makefile/47107132 From ff084fc0b00456256aaa2e70b876b57f6ffd3a40 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sun, 26 May 2024 21:03:31 -0700 Subject: [PATCH 03/11] Remove unnecessary asterisk from regex pattern --- Makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 9750f479f4..4b21f812d0 100644 --- a/Makefile +++ b/Makefile @@ -40,11 +40,11 @@ help: status @# made-up token — `#//` — and prints the target name (if present) 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 -n -e '/@sed/!s/\(^.*\)*:.*#\/\/ \(.*\)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) - @# -- -- -- --------------------- ---------------- - @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles + @# ↓ skip ↓ token ↙ ↘ ANSI escape codes (for color) + @# ------- ----- -------- ------- + @sed --silent -e '/@sed/!s/\(^.*\):.*#\/\/ \(.*\)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) + @# -- -- -- --------------------- ---------------- + @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles @# @# Reference: https://stackoverflow.com/questions/8889035/how-to-document-a-makefile/47107132 From ab7f6d1fba928612b1a80b194c286274f4882621 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sun, 26 May 2024 21:14:58 -0700 Subject: [PATCH 04/11] Use extended regex syntax so can omit some escape chars --- Makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 4b21f812d0..7483211c2b 100644 --- a/Makefile +++ b/Makefile @@ -40,11 +40,11 @@ help: status @# made-up token — `#//` — and prints the target name (if present) 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 -e '/@sed/!s/\(^.*\):.*#\/\/ \(.*\)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) - @# -- -- -- --------------------- ---------------- - @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles + @# ↓ skip ↓ token ↙ ↘ ANSI escape codes (for color) + @# ------- ----- -------- ------- + @sed --silent --regexp-extended '/@sed/!s/^([^[:space:]]+?):.*#\/\/ (.*)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) + @# -------------- -- -- --------------------- ---------------- + @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles @# @# Reference: https://stackoverflow.com/questions/8889035/how-to-document-a-makefile/47107132 From 48c23dfb0bc8fd0627f2dba40c46c50b8b1aaf57 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sun, 26 May 2024 21:16:56 -0700 Subject: [PATCH 05/11] Fix alignment of arrow in comment --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 7483211c2b..93407fd09e 100644 --- a/Makefile +++ b/Makefile @@ -44,7 +44,7 @@ help: status @# ------- ----- -------- ------- @sed --silent --regexp-extended '/@sed/!s/^([^[:space:]]+?):.*#\/\/ (.*)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) @# -------------- -- -- --------------------- ---------------- - @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles + @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles @# @# Reference: https://stackoverflow.com/questions/8889035/how-to-document-a-makefile/47107132 From bbda5dd9eefb7d9b5e488a5f33273fa07293db73 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sun, 26 May 2024 21:27:45 -0700 Subject: [PATCH 06/11] Update comment to match behavior of `sed` script --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 93407fd09e..898cfb6215 100644 --- a/Makefile +++ b/Makefile @@ -36,8 +36,8 @@ help: status @# @# Display a list of documented targets. @# - @# Note: This `@sed` command finds all the Makefile lines that contain a target name (optional) and contain the - @# made-up token — `#//` — and prints the target name (if present) and the post-token text to the console. + @# 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) From c6bd24fc8c2aa9b82f39d4201ad5a6293f6e2daf Mon Sep 17 00:00:00 2001 From: eecavanna Date: Fri, 12 Jul 2024 13:03:33 -0700 Subject: [PATCH 07/11] Document additional `make` targets --- Makefile | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 898cfb6215..fd4862ce18 100644 --- a/Makefile +++ b/Makefile @@ -162,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 #// Alias for "mkdocs serve" command (which runs Mkdocs web server) # Python datamodel $(PYMODEL): @@ -171,7 +171,7 @@ $(PYMODEL): $(DOCDIR): mkdir -p $@ -gendoc: $(DOCDIR) +gendoc: $(DOCDIR) #// Converts 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) ; \ @@ -179,7 +179,7 @@ gendoc: $(DOCDIR) mkdir -p $(DOCDIR)/javascripts $(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/ -testdoc: gendoc serve +testdoc: gendoc serve #// Generates Markdown files, converts them into HTML, and serves them MKDOCS = $(RUN) mkdocs mkd-%: @@ -229,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: #// Deletes project directory, temporary build artifacts, and generated doc files rm -rf $(DEST) rm -rf tmp rm -rf docs/*.md From adb3bf64098f60cc2a00d970438cac04159f4504 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Fri, 12 Jul 2024 21:03:22 -0700 Subject: [PATCH 08/11] Standardize mood (use imperative, not declarative) --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index fd4862ce18..2486611379 100644 --- a/Makefile +++ b/Makefile @@ -171,7 +171,7 @@ $(PYMODEL): $(DOCDIR): mkdir -p $@ -gendoc: $(DOCDIR) #// Converts schema content into Markdown files (in "docs" folder) +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) ; \ @@ -179,7 +179,7 @@ gendoc: $(DOCDIR) #// Converts schema content into Markdown files (in "docs" fo mkdir -p $(DOCDIR)/javascripts $(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/ -testdoc: gendoc serve #// Generates Markdown files, converts them into HTML, and serves them +testdoc: gendoc serve #// Generate Markdown files, convert them into HTML, and serve them MKDOCS = $(RUN) mkdocs mkd-%: @@ -230,7 +230,7 @@ git-status: touch $@ # TODO: Consider removing `rm -rf docs/*.html` since HTML files go to "site/", not "docs/". -clean: #// Deletes project directory, temporary build artifacts, and generated doc files +clean: #// Delete project directory, temporary build artifacts, and generated doc files rm -rf $(DEST) rm -rf tmp rm -rf docs/*.md From 81efbb2275e3d44a36a65fd3a964bf9b7317f9fc Mon Sep 17 00:00:00 2001 From: eecavanna Date: Fri, 12 Jul 2024 21:05:06 -0700 Subject: [PATCH 09/11] Emphasize effect more than description --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 2486611379..8621d756f9 100644 --- a/Makefile +++ b/Makefile @@ -162,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 #// Alias for "mkdocs serve" command (which runs Mkdocs web server) +serve: mkd-serve #// Run Mkdocs web server (alias for "mkdocs serve" command) # Python datamodel $(PYMODEL): From a0d96faa4427f79741066f1b782692179b59def9 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Fri, 12 Jul 2024 21:06:00 -0700 Subject: [PATCH 10/11] Remove unnecessary parentheses --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 8621d756f9..af1bc65ce3 100644 --- a/Makefile +++ b/Makefile @@ -171,7 +171,7 @@ $(PYMODEL): $(DOCDIR): mkdir -p $@ -gendoc: $(DOCDIR) #// Convert schema content into Markdown files (in "docs" folder) +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) ; \ From 6388e28222f49d95cb92f760fe9f53cb5014aa7f Mon Sep 17 00:00:00 2001 From: eecavanna Date: Fri, 12 Jul 2024 21:19:51 -0700 Subject: [PATCH 11/11] Sort list of documented target alphabetically --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index af1bc65ce3..a063b2b44e 100644 --- a/Makefile +++ b/Makefile @@ -42,7 +42,7 @@ help: status @# @# ↓ skip ↓ token ↙ ↘ ANSI escape codes (for color) @# ------- ----- -------- ------- - @sed --silent --regexp-extended '/@sed/!s/^([^[:space:]]+?):.*#\/\/ (.*)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) + @sed --silent --regexp-extended '/@sed/!s/^([^[:space:]]+?):.*#\/\/ (.*)/\x1b[35m\1\x1b[0m: \2/p' $(MAKEFILE_LIST) | sort @# -------------- -- -- --------------------- ---------------- @# target ↑ ↑ deps ↑ docs ↑ output ↑ all Makefiles @#