[Python] How would I re-write labels and references to be unique using a Sphinx extension?

I am using Sphinx to generate documentation.

I have few (<10) folders with a lot of (>50) generated rST files that contain descriptions, but the labels and references are not unique between folders.

folder_1
file_a
label a_text1
label a_text2
file_b
label b_text1
label b_text2
folder_2
file_a
label a_text1
label a_text2
file_b
label b_text1
label b_text2


Obviously Sphinx complains because the labels are not unique.

I tried to write a Sphinx extension that prefixes all labels/references based on the folder, so that labels become unique: a_text1 --> f1_a_text1

What would be the right event to modify this, doctree-read or doctree-resolved?

I can modify all targets after event doctree-read and all references after event doctree-resolved. Is that the right way to do it? Looks like I'm missing the sections.

def prefix_labels_read(app, doctree):
prefix = "myPrefix:"
print("sections -----------------------------------")
for section in doctree.traverse(nodes.section):
title = section.next_node(nodes.Titular)
if title:
print(title.astext())
print("targets -----------------------------------")
for node in doctree.findall(nodes.target):
if 'refid' in node:
node['refid'] = f"{prefix}{node['refid']}"
print(target)
print("references -----------------------------------")
# there are no references at this moment, all of them are still 'pending_xref'

def prefix_labels_resolved(app, doctree, docname):
print("targets -----------------------------------")
for target in doctree.findall(nodes.target):
# targets were already replaced in prefix_labels_read()
print(target)
print("references -----------------------------------")
for node in doctree.traverse(nodes.reference):
if 'refid' in node:
node['refid'] = f"{prefix}{node['refid']}"
if 'refuri' in node:
hashpos = node['refuri'].find('#')
if hashpos == -1:
node['refuri'] = f"{prefix}{node['refuri']}"
else:
node['refuri'] = f"{node['refuri'][:hashpos+1]}{prefix}{node['refuri'][hashpos+1:]}"

def setup(app: Sphinx) -> dict[str, Any]:
app.connect('doctree-read', prefix_labels_read)
app.connect('doctree-resolved', prefix_labels_resolved)

return {
'version': sphinx.__display_version__,
'parallel_read_safe': True,
'parallel_write_safe': True,
}

Continue reading...