In order to cross-reference C types in the documentation, Sphinx
requires the syntax :c:type:`type_name`, or even :c:type:`struct
type_name <type_name>` in order to have the link text different from the
target text.
This patch series removes the need for that markup.
The first commit extends the automarkup script to enable automatic
cross-reference of C types by matching any "struct|union|enum|typedef type_name"
expression.
This makes the documentation's plain text cleaner and adds cross-reference to
types without any additional effort by the author.
The second commit updates the "Cross-referencing from
reStructuredText" section in Documentation/doc-guide/kernel-doc.rst
to reflect that no additional syntax is needed when cross-referencing both types
and functions anymore.
When testing this, I did find an edge-case from the output of
Documentation/output/scsi/scsi_mid_low_api.rst on the "typedef struct scsi_cmnd
Scsi_Cmnd;", where 'typedef struct' is being identified as a reference, but
there isn't any named 'struct', so it renders bold.
I thought of adding an ignore_names list just like there is one for functions,
with 'struct' in it, to workaround this edge case, but since it was the only
one I found, and also because it was unclear what the desired output was
(cross-reference 'struct scsi_cmnd' or leave the whole expression as plain text)
I wanted to get some feedback beforehand.
After getting this merged I intend to start removing the occurrences of :c:type.
Thanks,
Nícolas
Nícolas F. R. A. Prado (2):
docs: Add automatic cross-reference for C types
kernel-doc: Update "cross-referencing from rST" section to use
automarkup
Documentation/doc-guide/kernel-doc.rst | 33 ++++++++++++-----------
Documentation/sphinx/automarkup.py | 37 +++++++++++++++++---------
2 files changed, 41 insertions(+), 29 deletions(-)
--
2.28.0
