From 176a622387f90850637dc45f1d5ba3fcf7a62735 Mon Sep 17 00:00:00 2001 From: gururaj1512 Date: Tue, 4 Aug 2026 21:04:51 +0530 Subject: [PATCH] build: add recipes for processing markdown figures Add make targets and file listing utilities for parsing markdown figure comments, inserting HTML figure elements, replacing local image paths with jsDelivr CDN URLs, and cleaning SVG figure assets. --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown_pkg_readmes status: na - task: lint_markdown_docs status: na - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- tools/make/lib/ls/Makefile | 8 ++ tools/make/lib/ls/svg_figures.mk | 49 +++++++ tools/make/lib/markdown/Makefile | 1 + tools/make/lib/markdown/figures.mk | 220 +++++++++++++++++++++++++++++ 4 files changed, 278 insertions(+) create mode 100644 tools/make/lib/ls/svg_figures.mk create mode 100644 tools/make/lib/markdown/figures.mk diff --git a/tools/make/lib/ls/Makefile b/tools/make/lib/ls/Makefile index adc7a91fdd93..c4cd7151a692 100644 --- a/tools/make/lib/ls/Makefile +++ b/tools/make/lib/ls/Makefile @@ -239,6 +239,13 @@ SVG_EQUATIONS_PATTERN ?= equation*.$(SVG_FILENAME_EXT) SVG_EQUATIONS_FILTER ?= .*/.* +# Define a filename pattern for SVG figure files: +SVG_FIGURES_PATTERN ?= fig*.$(SVG_FILENAME_EXT) + +# Define a filepath pattern for SVG figure files: +SVG_FIGURES_FILTER ?= .*/.* + + # Define a filename pattern for TypeScript files: TYPESCRIPT_PATTERN ?= *.$(TYPESCRIPT_FILENAME_EXT) @@ -441,6 +448,7 @@ include $(TOOLS_MAKE_LIB_DIR)/ls/python/Makefile include $(TOOLS_MAKE_LIB_DIR)/ls/r/Makefile include $(TOOLS_MAKE_LIB_DIR)/ls/shell/Makefile include $(TOOLS_MAKE_LIB_DIR)/ls/svg_equations.mk +include $(TOOLS_MAKE_LIB_DIR)/ls/svg_figures.mk include $(TOOLS_MAKE_LIB_DIR)/ls/tests_directories.mk include $(TOOLS_MAKE_LIB_DIR)/ls/tests_fixtures.mk include $(TOOLS_MAKE_LIB_DIR)/ls/tools_tests_directories.mk diff --git a/tools/make/lib/ls/svg_figures.mk b/tools/make/lib/ls/svg_figures.mk new file mode 100644 index 000000000000..8023e5eeb027 --- /dev/null +++ b/tools/make/lib/ls/svg_figures.mk @@ -0,0 +1,49 @@ +#/ +# @license Apache-2.0 +# +# Copyright (c) 2026 The Stdlib Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#/ + +# VARIABLES # + +# Define the command flags: +FIND_SVG_FIGURES_FLAGS ?= \ + -type f \ + -name "$(SVG_FIGURES_PATTERN)" \ + -path "$(ROOT_DIR)/**/$(DOCUMENTATION_FOLDER)/**" \ + -regex "$(SVG_FIGURES_FILTER)" \ + $(FIND_SVG_EQUATIONS_EXCLUDE_FLAGS) + +ifneq ($(OS), Darwin) + FIND_SVG_FIGURES_FLAGS := -regextype posix-extended $(FIND_SVG_FIGURES_FLAGS) +endif + +# Define a command for listing SVG figure files: +FIND_SVG_FIGURES_CMD ?= find $(find_kernel_prefix) $(ROOT_DIR) $(FIND_SVG_FIGURES_FLAGS) + +# Define the list of files: +SVG_FIGURE_FILES ?= $(shell $(FIND_SVG_FIGURES_CMD)) + + +# TARGETS # + +# List all SVG figure files. +# +# This target prints a list of all SVG figure files. + +list-svg-figure-files: + $(QUIET) find $(find_kernel_prefix) $(ROOT_DIR) $(FIND_SVG_FIGURES_FLAGS) $(find_print_list) + +.PHONY: list-svg-figure-files diff --git a/tools/make/lib/markdown/Makefile b/tools/make/lib/markdown/Makefile index 3f3096b55c9b..3787a9ad3580 100644 --- a/tools/make/lib/markdown/Makefile +++ b/tools/make/lib/markdown/Makefile @@ -21,6 +21,7 @@ # Note: keep in alphabetical order... include $(TOOLS_MAKE_LIB_DIR)/markdown/assets.mk include $(TOOLS_MAKE_LIB_DIR)/markdown/equations.mk +include $(TOOLS_MAKE_LIB_DIR)/markdown/figures.mk include $(TOOLS_MAKE_LIB_DIR)/markdown/includes.mk include $(TOOLS_MAKE_LIB_DIR)/markdown/namespace_toc.mk include $(TOOLS_MAKE_LIB_DIR)/markdown/pkg_urls.mk diff --git a/tools/make/lib/markdown/figures.mk b/tools/make/lib/markdown/figures.mk new file mode 100644 index 000000000000..a7e609a31d4f --- /dev/null +++ b/tools/make/lib/markdown/figures.mk @@ -0,0 +1,220 @@ +#/ +# @license Apache-2.0 +# +# Copyright (c) 2026 The Stdlib Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#/ + +# VARIABLES # + +# Define the command to commit staged files after processing Markdown figures: +GIT_COMMIT_FIGURES ?= $(GIT_COMMIT) -m 'Process Markdown figures' + +# Define the command to commit staged files after inserting resource URLs: +GIT_COMMIT_FIGURES_SRC_URLS ?= $(GIT_COMMIT) -m 'Insert src urls into figure elements' + +# Define the path relative to a processed Markdown file for storing figure resources: +FIGURE_RESOURCES_PATH ?= ./docs/img/ + +# Define the path to the remark configuration file: +REMARK_FIGURES_CONF ?= $(CONFIG_DIR)/remark/.remarkrc.js + +# Define the path to the remark ignore file: +REMARK_FIGURES_IGNORE ?= $(ROOT_DIR)/.remarkignore + +# Define the path to a plugin which processes Markdown figure comments: +REMARK_IMG_FIGURES_PLUGIN ?= $(TOOLS_PKGS_DIR)/remark/plugins/remark-img-figures +REMARK_IMG_FIGURES_PLUGIN_SETTINGS ?= +REMARK_IMG_FIGURES_PLUGIN_FLAGS ?= --use $(REMARK_IMG_FIGURES_PLUGIN)=$(REMARK_IMG_FIGURES_PLUGIN_SETTINGS) + +# Define the path to a plugin which inserts resource URLs into Markdown image figure elements: +REMARK_IMG_FIGURES_SRC_URLS_PLUGIN ?= $(TOOLS_PKGS_DIR)/remark/plugins/remark-img-figures-src-urls +REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_SETTINGS ?= '"'dir'"':'"'$(FIGURE_RESOURCES_PATH)'"' +REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS ?= --use $(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN)=$(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_SETTINGS) + +# Define command-line options when invoking the remark executable: +REMARK_FIGURES_FLAGS ?= \ + --ext $(MARKDOWN_FILENAME_EXT) \ + --rc-path $(REMARK_FIGURES_CONF) \ + --ignore-path $(REMARK_FIGURES_IGNORE) + +# Define the remark output option: +REMARK_FIGURES_OUTPUT_FLAG ?= --output + + +# RULES # + +#/ +# Processes Markdown files containing Markdown figure elements. +# +# ## Notes +# +# - Processing happens as follows: +# +# 1. Files containing figure comments are transformed to include figure elements. +# 2. Processed files are committed to source control. +# 3. Resource URLs are inserted into image figure elements. +# 4. Processed files are committed to source control. +# +# - This rule is useful when wanting to glob for Markdown files (e.g., process all Markdown files for a particular package). +# +# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`) +# @param {string} [MARKDOWN_PATTERN] - filename pattern (e.g., `*.md`) +# +# @example +# make markdown-figures +# +# @example +# make markdown-figures MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/plot/vega/.*' +#/ +markdown-figures: $(NODE_MODULES) assert-clean-working-directory + $(QUIET) $(REMARK) $(MARKDOWN_FILES) \ + $(REMARK_FIGURES_FLAGS) \ + $(REMARK_IMG_FIGURES_PLUGIN_FLAGS) \ + $(REMARK_FIGURES_OUTPUT_FLAG) && \ + $(GIT_ADD) -A && $(GIT_COMMIT_FIGURES) && \ + $(REMARK) $(MARKDOWN_FILES) \ + $(REMARK_FIGURES_FLAGS) \ + $(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS) \ + $(REMARK_FIGURES_OUTPUT_FLAG) && \ + $(GIT_ADD) -A && $(GIT_COMMIT_FIGURES_SRC_URLS) + +.PHONY: markdown-figures + +#/ +# Transforms Markdown files containing figure comment markup to include image figure elements. +# +# ## Notes +# +# - This rule is useful when wanting to glob for Markdown files (e.g., process all Markdown files for a particular package). +# +# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`) +# @param {string} [MARKDOWN_PATTERN] - filename pattern (e.g., `*.md`) +# +# @example +# make markdown-img-figures +# +# @example +# make markdown-img-figures MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/plot/vega/.*' +#/ +markdown-img-figures: $(NODE_MODULES) + $(QUIET) $(FIND_MARKDOWN_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \ + echo ""; \ + echo "Processing file: $$file"; \ + "$(REMARK)" \ + $$file \ + $(REMARK_FIGURES_FLAGS) \ + $(REMARK_IMG_FIGURES_PLUGIN_FLAGS) \ + $(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \ + done + +.PHONY: markdown-img-figures + +#/ +# Transforms a specified list of Markdown files containing figure comment markup to include image figure elements. +# +# ## Notes +# +# - This rule is useful when wanting to process a list of Markdown files generated by some other command (e.g., a list of changed Markdown files obtained via `git diff`). +# +# @param {string} FILES - list of files +# +# @example +# make markdown-img-figures-files FILES='/foo/foo.md /foo/bar.md' +#/ +markdown-img-figures-files: $(NODE_MODULES) + $(QUIET) for file in $(FILES); do \ + echo ""; \ + echo "Processing file: $$file"; \ + "$(REMARK)" \ + $$file \ + $(REMARK_FIGURES_FLAGS) \ + $(REMARK_IMG_FIGURES_PLUGIN_FLAGS) \ + $(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \ + done + +.PHONY: markdown-img-figures-files + +#/ +# Inserts resource URLs into Markdown image figure elements. +# +# ## Notes +# +# - This rule is useful when wanting to glob for Markdown files (e.g., process all Markdown files for a particular package). +# - This recipe assumes that image SVG figure files already exist and have been committed to source control. +# +# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`) +# @param {string} [MARKDOWN_PATTERN] - filename pattern (e.g., `*.md`) +# +# @example +# make markdown-img-figures-src-urls +# +# @example +# make markdown-img-figures-src-urls MARKDOWN_PATTERN='README.md' MARKDOWN_FILTER='.*/plot/vega/.*' +#/ +markdown-img-figures-src-urls: $(NODE_MODULES) + $(QUIET) $(FIND_MARKDOWN_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \ + echo ""; \ + echo "Processing file: $$file"; \ + "$(REMARK)" \ + $$file \ + $(REMARK_FIGURES_FLAGS) \ + $(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS) \ + $(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \ + done + +.PHONY: markdown-img-figures-src-urls + +#/ +# Inserts resource URLs into Markdown image figure elements for a specified list of files. +# +# ## Notes +# +# - This rule is useful when wanting to process a list of Markdown files generated by some other command (e.g., a list of changed Markdown files obtained via `git diff`). +# - This recipe assumes that image SVG figure files already exist and have been committed to source control. +# +# @param {string} FILES - list of files +# +# @example +# make markdown-img-figures-src-urls-files FILES='/foo/foo.md /foo/bar.md' +#/ +markdown-img-figures-src-urls-files: $(NODE_MODULES) + $(QUIET) for file in $(FILES); do \ + echo ""; \ + echo "Processing file: $$file"; \ + "$(REMARK)" \ + $$file \ + $(REMARK_FIGURES_FLAGS) \ + $(REMARK_IMG_FIGURES_SRC_URLS_PLUGIN_FLAGS) \ + $(REMARK_FIGURES_OUTPUT_FLAG) || exit 1; \ + done + +.PHONY: markdown-img-figures-src-urls-files + +#/ +# Removes SVG figure files. +# +# @param {string} [SVG_FIGURES_FILTER] - file path pattern (e.g., `.*/plot/vega/.*`) +# @param {string} [SVG_FIGURES_PATTERN] - filename pattern (e.g., `fig*.svg`) +# +# @example +# make clean-markdown-svg-figures +# +# @example +# make clean-markdown-svg-figures SVG_FIGURES_PATTERN='fig*.svg' SVG_FIGURES_FILTER='.*/plot/vega/.*' +#/ +clean-markdown-svg-figures: + $(QUIET) $(DELETE) -f $(SVG_FIGURE_FILES) + +.PHONY: clean-markdown-svg-figures