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