On 9/2/20 5:58 PM, Nícolas F. R. A. Prado wrote: > 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. There also isn't any file name scsi_typedefs.h any longer, so maybe we can update scsi_mid_low_api.rst as well. Thanks. > 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(-) > -- ~Randy
