[PATCH] scripts/kernel-doc: add internal hyperlink to DOC: sections

While DOC: section titles are not converted into RST headings
sections and are only decorated with strong emphasis markup,
nothing stops us from generating internal hyperlinks for them,
to mimic implicit hyperlinks to RST headings.

Signed-off-by: Michal Wajdeczko <redacted>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jani Nikula <redacted>
Cc: Chris Wilson <redacted>
---
 scripts/kernel-doc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 6325bec3f66f..272f70c9fb13 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc

@@ -833,6 +833,7 @@ sub output_blockhead_rst(%) {
 	next if (defined($nosymbol_table{$section}));
 
 	if ($output_selection != OUTPUT_INCLUDE) {
+	    print ".. _$section:\n\n";
 	    print "**$section**\n\n";
 	}
         print_lineno($section_start_lines{$section});

-- 
2.25.1

On Mon, 18 Jan 2021 12:08:13 +0100
Michal Wajdeczko [off-list ref] wrote:

While DOC: section titles are not converted into RST headings
sections and are only decorated with strong emphasis markup,
nothing stops us from generating internal hyperlinks for them,
to mimic implicit hyperlinks to RST headings.

Signed-off-by: Michal Wajdeczko <redacted>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jani Nikula <redacted>
Cc: Chris Wilson <redacted>

So I've applied this, but ...

...the placement within this if means that the section marker doesn't
appear whenever a doc block is explicitly included with the :doc: modifier
- which I think is much of the time.  I *think* the marker should be
output unconditionally.

Jani, you appear to be the culprit behind that particular "if", which
seems a little questionable to me in general at the moment, but you must
have had a good reason.  Do you see any reason why a section marker should
be suppressed in the same way?

Thanks,

jon