`Audit events table` doc section is generated with broken links

[arhadthedev]

Parent issue: gh-93851

https://docs.python.org/3/library/audit_events.html has two links to non-existent sections of sqlite3.html:

• sqlite3.enable_load_extension | connection, enabled | [1]
• sqlite3.load_extension | connection, path | [1]

I couldn't find where these lines come from. A source file https://github.com/python/cpython/blob/ff095e13dfdea64de5c1ad21021ae9b5ca2631f8/Doc/library/audit_events.rst is much shorter, and I don't know what to grep.

[erlend-aasland]

https://docs.python.org/3/library/audit_events.html has two links to non-existent sections of sqlite3.html:

• sqlite3.enable_load_extension | connection, enabled | [1]
• sqlite3.load_extension | connection, path | [1]

They are not non-existent, they just live under the sqlite3.Connection namespace. The audit names, however, are sqlite3.enable_load_extension and sqlite3.load_extension.

I couldn't find where these lines come from. A source file https://github.com/python/cpython/blob/ff095e13dfdea64de5c1ad21021ae9b5ca2631f8/Doc/library/audit_events.rst is much shorter, and I don't know what to grep.

That file is partly autogenerated, as noted on line 17.

This table is generated from the CPython documentation [...]

I suspect we need to alter the audit-event Sphinx extension to fix these things:

cpython/Doc/tools/extensions/pyspecific.py

Lines 189 to 278 in ff095e1

	class AuditEvent(Directive):
	has_content = True
	required_arguments = 1
	optional_arguments = 2
	final_argument_whitespace = True
	_label = [
	"Raises an :ref:`auditing event <auditing>` {name} with no arguments.",
	"Raises an :ref:`auditing event <auditing>` {name} with argument {args}.",
	"Raises an :ref:`auditing event <auditing>` {name} with arguments {args}.",
	]
	@property
	def logger(self):
	cls = type(self)
	return logging.getLogger(cls.__module__ + "." + cls.__name__)
	def run(self):
	name = self.arguments[0]
	if len(self.arguments) >= 2 and self.arguments[1]:
	args = (a.strip() for a in self.arguments[1].strip("'\"").split(","))
	args = [a for a in args if a]
	else:
	args = []
	label = translators['sphinx'].gettext(self._label[min(2, len(args))])
	text = label.format(name="``{}``".format(name),
	args=", ".join("``{}``".format(a) for a in args if a))
	env = self.state.document.settings.env
	if not hasattr(env, 'all_audit_events'):
	env.all_audit_events = {}
	new_info = {
	'source': [],
	'args': args
	}
	info = env.all_audit_events.setdefault(name, new_info)
	if info is not new_info:
	if not self._do_args_match(info['args'], new_info['args']):
	self.logger.warn(
	"Mismatched arguments for audit-event {}: {!r} != {!r}"
	.format(name, info['args'], new_info['args'])
	)
	ids = []
	try:
	target = self.arguments[2].strip("\"'")
	except (IndexError, TypeError):
	target = None
	if not target:
	target = "audit_event_{}_{}".format(
	re.sub(r'\W', '_', name),
	len(info['source']),
	)
	ids.append(target)
	info['source'].append((env.docname, target))
	pnode = nodes.paragraph(text, classes=["audit-hook"], ids=ids)
	pnode.line = self.lineno
	if self.content:
	self.state.nested_parse(self.content, self.content_offset, pnode)
	else:
	n, m = self.state.inline_text(text, self.lineno)
	pnode.extend(n + m)
	return [pnode]
	# This list of sets are allowable synonyms for event argument names.
	# If two names are in the same set, they are treated as equal for the
	# purposes of warning. This won't help if number of arguments is
	# different!
	_SYNONYMS = [
	{"file", "path", "fd"},
	]
	def _do_args_match(self, args1, args2):
	if args1 == args2:
	return True
	if len(args1) != len(args2):
	return False
	for a1, a2 in zip(args1, args2):
	if a1 == a2:
	continue
	if any(a1 in s and a2 in s for s in self._SYNONYMS):
	continue
	return False
	return True

[erlend-aasland]

[...] I don't know what to grep.

$ grep -r "audit-event::" Doc/
$ grep -r "audit-event::.*sqlite" Doc/

[erlend-aasland]

I suspect we need to alter the audit-event Sphinx extension to fix these things [...]

Or maybe we're using the audit-event directive wrongly in Doc/library/sqlite3.rst.

[erlend-aasland]

Yay, it was the latter. So we don't need to dig around in the Python Sphinx extensions (phew!) :)

[erlend-aasland]

FTR, the third argument to the audit-event directive is the target:

cpython/Doc/tools/extensions/pyspecific.py

Lines 236 to 243 in ff095e1

	try:
	target = self.arguments[2].strip("\"'")
	except (IndexError, TypeError):
	target = None
	if not target:
	target = "audit_event_{}_{}".format(
	re.sub(r'\W', '_', name),
	len(info['source']),