Add scheme support for Jinja `line_comment_prefix` and `line_statement_prefix`

[JoeyC-Dev]

I noticed that mkdocs-macros-plugin can already forward arbitrary j2_* config values to jinja2.Environment, but some valid Jinja environment options are not declared in the plugin config scheme.

For example:

plugins:
  - search
  - awesome-pages
  - macros:
      include_dir: examples
      j2_line_comment_prefix: "#$"

Src: https://github.com/kubernetes-sigs/gateway-api/blob/6239dcf644cc25593b8ae8c5abc070756cde8218/mkdocs.yml#L17-L22

works at runtime because the plugin strips the j2_ prefix and forwards the value to Jinja as:

line_comment_prefix="#$"

Relevant code in mkdocs_macros/plugin.py:

mkdocs-macros-plugin/mkdocs_macros/plugin.py

Lines 837 to 850 in 0536f4d

	# read the config variables for jinja2:
	for key, value in self.config.items():
	# take definitions in config_scheme where key starts with 'j2_'
	# (if value is not empty)
	# and forward them to jinja2
	# this is used for the markers
	if key.startswith('j2_') and value:
	variable_name = key.split('_', 1)[1] # remove prefix
	trace("Found j2 variable '%s': '%s'" %
	(variable_name, value))
	env_config[variable_name] = value
	# finally build the environment:
	self._env = Environment(**env_config)

mkdocs-macros-plugin/mkdocs_macros/plugin.py

Lines 121 to 155 in 0536f4d

	config_scheme = (
	# main python module:
	('module_name', PluginType(str,
	default=DEFAULT_MODULE_NAME)),
	('modules', PluginType(list,
	default=[])),
	# How to render pages by default: yes (opt-out), no (opt-in)
	('render_by_default', PluginType(bool, default=True)),
	# Force the rendering of those directories and files
	# Use Pathspec syntax (similar to gitignore)
	# see: https://python-path-specification.readthedocs.io/en/stable/readme.html#tutorial
	# this is relative to doc_dir
	('force_render_paths', J2_STRING),
	# Include directory for external files
	# also works for {% include ....%}) and {% import ....%}):
	('include_dir', J2_STRING),
	# list of additional yaml files:
	('include_yaml', PluginType(list, default=[])),
	# for altering the j2 markers, in case of need:
	# https://jinja.palletsprojects.com/en/latest/api/
	('j2_block_start_string', J2_STRING),
	('j2_block_end_string', J2_STRING),
	('j2_variable_start_string', J2_STRING),
	('j2_variable_end_string', J2_STRING),
	('j2_comment_start_string', J2_STRING),
	('j2_comment_end_string', J2_STRING),
	# for including j2 extensions:
	# https://jinja.palletsprojects.com/en/stable/extensions/
	('j2_extensions', J2_STRING_LIST),
	# for behavior of unknown macro (e.g. other plugin):
	('on_undefined', PluginType(str, default=DEFAULT_UNDEFINED_BEHAVIOR)),
	# for CD/CI set that parameter to true
	('on_error_fail', PluginType(bool, default=False)),
	('verbose', PluginType(bool, default=False))
	)

However, because j2_line_comment_prefix is not listed in config_scheme, MkDocs emits a config warning:

WARNING -  Config value 'plugins': Plugin 'macros' option 'j2_line_comment_prefix': Unrecognised configuration name: j2_line_comment_prefix

Jinja documents line_statement_prefix and line_comment_prefix as supported environment options:

Line Statements and Comments are also possible, though they don’t have default prefix characters. To use them, set line_statement_prefix and line_comment_prefix when creating the Environment.

Src: https://jinja.palletsprojects.com/en/stable/templates/#:~:text=line_statement_prefix

And also here:

Src: https://jinja.palletsprojects.com/en/stable/api/#jinja2.Environment

To fix this issue, we can add these options to the plugin.

('j2_line_statement_prefix', J2_STRING),
('j2_line_comment_prefix', J2_STRING),

Background

This warning has already caused a real downstream regression.

In Kubernetes Gateway API's project site, the project used:

plugins:
  - macros:
      include_dir: examples
      j2_line_comment_prefix: "#$"

To hide metadata comments in included YAML examples, such as:

#$ Used in:
#$ - site-src/api-types/httproute.md
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute

Because j2_line_comment_prefix works at runtime but is not recognized by the plugin schema, the contributor simply removed it in kubernetes-sigs/gateway-api#3999 (review) due to the warning emitted, which led to a site regression.

[github-actions]

Welcome to this project and thank you!