[linux-block.git] / Documentation / sphinx / automarkup.py

# SPDX-License-Identifier: GPL-2.0
# Copyright 2019 Jonathan Corbet <corbet@lwn.net>
#
# Apply kernel-specific tweaks after the initial document processing
# has been done.
#
from docutils import nodes
import sphinx
from sphinx import addnodes
if sphinx.version_info[0] < 2 or \
   sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1:
    from sphinx.environment import NoUri
else:
    from sphinx.errors import NoUri
import re
from itertools import chain

#
# Python 2 lacks re.ASCII...
#
try:
    ascii_p3 = re.ASCII
except AttributeError:
    ascii_p3 = 0

#
# Regex nastiness.  Of course.
# Try to identify "function()" that's not already marked up some
# other way.  Sphinx doesn't like a lot of stuff right after a
# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last
# bit tries to restrict matches to things that won't create trouble.
#
RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=ascii_p3)

#
# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
#
RE_generic_type = re.compile(r'\b(struct|union|enum|typedef)\s+([a-zA-Z_]\w+)',
                             flags=ascii_p3)

#
# Sphinx 3 uses a different C role for each one of struct, union, enum and
# typedef
#
RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3)

#
# Detects a reference to a documentation page of the form Documentation/... with
# an optional extension
#
RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')

RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')

#
# Reserved C words that we should skip when cross-referencing
#
Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]


#
# Many places in the docs refer to common system calls.  It is
# pointless to try to cross-reference them and, as has been known
# to happen, somebody defining a function by these names can lead
# to the creation of incorrect and confusing cross references.  So
# just don't even try with these names.
#
Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
              'select', 'poll', 'fork', 'execve', 'clone', 'ioctl',
              'socket' ]

c_namespace = ''

def markup_refs(docname, app, node):
    t = node.astext()
    done = 0
    repl = [ ]
    #
    # Associate each regex with the function that will markup its matches
    #
    markup_func_sphinx2 = {RE_doc: markup_doc_ref,
                           RE_function: markup_c_ref,
                           RE_generic_type: markup_c_ref}

    markup_func_sphinx3 = {RE_doc: markup_doc_ref,
                           RE_function: markup_func_ref_sphinx3,
                           RE_struct: markup_c_ref,
                           RE_union: markup_c_ref,
                           RE_enum: markup_c_ref,
                           RE_typedef: markup_c_ref}

    if sphinx.version_info[0] >= 3:
        markup_func = markup_func_sphinx3
    else:
        markup_func = markup_func_sphinx2

    match_iterators = [regex.finditer(t) for regex in markup_func]
    #
    # Sort all references by the starting position in text
    #
    sorted_matches = sorted(chain(*match_iterators), key=lambda m: m.start())
    for m in sorted_matches:
        #
        # Include any text prior to match as a normal text node.
        #
        if m.start() > done:
            repl.append(nodes.Text(t[done:m.start()]))

        #
        # Call the function associated with the regex that matched this text and
        # append its return to the text
        #
        repl.append(markup_func[m.re](docname, app, m))

        done = m.end()
    if done < len(t):
        repl.append(nodes.Text(t[done:]))
    return repl

#
# In sphinx3 we can cross-reference to C macro and function, each one with its
# own C role, but both match the same regex, so we try both.
#
def markup_func_ref_sphinx3(docname, app, match):
    class_str = ['c-func', 'c-macro']
    reftype_str = ['function', 'macro']

    cdom = app.env.domains['c']
    #
    # Go through the dance of getting an xref out of the C domain
    #
    base_target = match.group(2)
    target_text = nodes.Text(match.group(0))
    xref = None
    possible_targets = [base_target]
    # Check if this document has a namespace, and if so, try
    # cross-referencing inside it first.
    if c_namespace:
        possible_targets.insert(0, c_namespace + "." + base_target)

    if base_target not in Skipnames:
        for target in possible_targets:
            if target not in Skipfuncs:
                for class_s, reftype_s in zip(class_str, reftype_str):
                    lit_text = nodes.literal(classes=['xref', 'c', class_s])
                    lit_text += target_text
                    pxref = addnodes.pending_xref('', refdomain = 'c',
                                                  reftype = reftype_s,
                                                  reftarget = target, modname = None,
                                                  classname = None)
                    #
                    # XXX The Latex builder will throw NoUri exceptions here,
                    # work around that by ignoring them.
                    #
                    try:
                        xref = cdom.resolve_xref(app.env, docname, app.builder,
                                                 reftype_s, target, pxref,
                                                 lit_text)
                    except NoUri:
                        xref = None

                    if xref:
                        return xref

    return target_text

def markup_c_ref(docname, app, match):
    class_str = {# Sphinx 2 only
                 RE_function: 'c-func',
                 RE_generic_type: 'c-type',
                 # Sphinx 3+ only
                 RE_struct: 'c-struct',
                 RE_union: 'c-union',
                 RE_enum: 'c-enum',
                 RE_typedef: 'c-type',
                 }
    reftype_str = {# Sphinx 2 only
                   RE_function: 'function',
                   RE_generic_type: 'type',
                   # Sphinx 3+ only
                   RE_struct: 'struct',
                   RE_union: 'union',
                   RE_enum: 'enum',
                   RE_typedef: 'type',
                   }

    cdom = app.env.domains['c']
    #
    # Go through the dance of getting an xref out of the C domain
    #
    base_target = match.group(2)
    target_text = nodes.Text(match.group(0))
    xref = None
    possible_targets = [base_target]
    # Check if this document has a namespace, and if so, try
    # cross-referencing inside it first.
    if c_namespace:
        possible_targets.insert(0, c_namespace + "." + base_target)

    if base_target not in Skipnames:
        for target in possible_targets:
            if not (match.re == RE_function and target in Skipfuncs):
                lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
                lit_text += target_text
                pxref = addnodes.pending_xref('', refdomain = 'c',
                                              reftype = reftype_str[match.re],
                                              reftarget = target, modname = None,
                                              classname = None)
                #
                # XXX The Latex builder will throw NoUri exceptions here,
                # work around that by ignoring them.
                #
                try:
                    xref = cdom.resolve_xref(app.env, docname, app.builder,
                                             reftype_str[match.re], target, pxref,
                                             lit_text)
                except NoUri:
                    xref = None

                if xref:
                    return xref

    return target_text

#
# Try to replace a documentation reference of the form Documentation/... with a
# cross reference to that page
#
def markup_doc_ref(docname, app, match):
    stddom = app.env.domains['std']
    #
    # Go through the dance of getting an xref out of the std domain
    #
    absolute = match.group(1)
    target = match.group(2)
    if absolute:
       target = "/" + target
    xref = None
    pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc',
                                  reftarget = target, modname = None,
                                  classname = None, refexplicit = False)
    #
    # XXX The Latex builder will throw NoUri exceptions here,
    # work around that by ignoring them.
    #
    try:
        xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc',
                                   target, pxref, None)
    except NoUri:
        xref = None
    #
    # Return the xref if we got it; otherwise just return the plain text.
    #
    if xref:
        return xref
    else:
        return nodes.Text(match.group(0))

def get_c_namespace(app, docname):
    source = app.env.doc2path(docname)
    with open(source) as f:
        for l in f:
            match = RE_namespace.search(l)
            if match:
                return match.group(1)
    return ''

def auto_markup(app, doctree, name):
    global c_namespace
    c_namespace = get_c_namespace(app, name)
    def text_but_not_a_reference(node):
        # The nodes.literal test catches ``literal text``, its purpose is to
        # avoid adding cross-references to functions that have been explicitly
        # marked with cc:func:.
        if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal):
            return False

        child_of_reference = False
        parent = node.parent
        while parent:
            if isinstance(parent, nodes.Referential):
                child_of_reference = True
                break
            parent = parent.parent
        return not child_of_reference

    #
    # This loop could eventually be improved on.  Someday maybe we
    # want a proper tree traversal with a lot of awareness of which
    # kinds of nodes to prune.  But this works well for now.
    #
    for para in doctree.traverse(nodes.paragraph):
        for node in para.traverse(condition=text_but_not_a_reference):
            node.parent.replace(node, markup_refs(name, app, node))

def setup(app):
    app.connect('doctree-resolved', auto_markup)
    return {
        'parallel_read_safe': True,
        'parallel_write_safe': True,
        }
Commit	Line	Data
d74b0d31 JC	1	# SPDX-License-Identifier: GPL-2.0
	2	# Copyright 2019 Jonathan Corbet <corbet@lwn.net>
	3	#
	4	# Apply kernel-specific tweaks after the initial document processing
	5	# has been done.
	6	#
	7	from docutils import nodes
bcac386f	8	import sphinx
d74b0d31	9	from sphinx import addnodes
bcac386f JC	10	if sphinx.version_info[0] < 2 or \
	11	sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1:
	12	from sphinx.environment import NoUri
	13	else:
	14	from sphinx.errors import NoUri
d74b0d31	15	import re
d82b1e83	16	from itertools import chain
d74b0d31	17
4f3e6906 JC	18	#
	19	# Python 2 lacks re.ASCII...
	20	#
	21	try:
	22	ascii_p3 = re.ASCII
	23	except AttributeError:
	24	ascii_p3 = 0
	25
d74b0d31 JC	26	#
	27	# Regex nastiness. Of course.
	28	# Try to identify "function()" that's not already marked up some
	29	# other way. Sphinx doesn't like a lot of stuff right after a
	30	# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last
	31	# bit tries to restrict matches to things that won't create trouble.
	32	#
4f3e6906	33	RE_function = re.compile(r'\b(([a-zA-Z_]\w+)\(\))', flags=ascii_p3)
06dc65b0 NP	34
	35	#
	36	# Sphinx 2 uses the same :c:type role for struct, union, enum and typedef
	37	#
f66e47f9	38	RE_generic_type = re.compile(r'\b(struct\|union\|enum\|typedef)\s+([a-zA-Z_]\w+)',
4f3e6906	39	flags=ascii_p3)
06dc65b0 NP	40
	41	#
	42	# Sphinx 3 uses a different C role for each one of struct, union, enum and
	43	# typedef
	44	#
4f3e6906 JC	45	RE_struct = re.compile(r'\b(struct)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
	46	RE_union = re.compile(r'\b(union)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
	47	RE_enum = re.compile(r'\b(enum)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
	48	RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
06dc65b0	49
d18b0178 NP	50	#
	51	# Detects a reference to a documentation page of the form Documentation/... with
	52	# an optional extension
	53	#
ea1d8389	54	RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst\|txt)')
d74b0d31	55
fb568273 NP	56	RE_namespace = re.compile(r'^\s..\sc:namespace::\s(\S+)\s$')
fb568273 NP	57
3050edfd NP	58	#
	59	# Reserved C words that we should skip when cross-referencing
	60	#
	61	Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
	62
	63
d74b0d31 JC	64	#
	65	# Many places in the docs refer to common system calls. It is
	66	# pointless to try to cross-reference them and, as has been known
	67	# to happen, somebody defining a function by these names can lead
	68	# to the creation of incorrect and confusing cross references. So
	69	# just don't even try with these names.
	70	#
11fec009	71	Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
82bf829b JN	72	'select', 'poll', 'fork', 'execve', 'clone', 'ioctl',
82bf829b JN	73	'socket' ]
d74b0d31	74
fb568273 NP	75	c_namespace = ''
fb568273 NP	76
1ac4cfb2	77	def markup_refs(docname, app, node):
d74b0d31 JC	78	t = node.astext()
	79	done = 0
	80	repl = [ ]
d82b1e83	81	#
1ac4cfb2 NP	82	# Associate each regex with the function that will markup its matches
1ac4cfb2 NP	83	#
06dc65b0 NP	84	markup_func_sphinx2 = {RE_doc: markup_doc_ref,
	85	RE_function: markup_c_ref,
	86	RE_generic_type: markup_c_ref}
	87
	88	markup_func_sphinx3 = {RE_doc: markup_doc_ref,
c51d9b04	89	RE_function: markup_func_ref_sphinx3,
06dc65b0 NP	90	RE_struct: markup_c_ref,
	91	RE_union: markup_c_ref,
	92	RE_enum: markup_c_ref,
	93	RE_typedef: markup_c_ref}
	94
	95	if sphinx.version_info[0] >= 3:
	96	markup_func = markup_func_sphinx3
	97	else:
	98	markup_func = markup_func_sphinx2
	99
1ac4cfb2	100	match_iterators = [regex.finditer(t) for regex in markup_func]
d82b1e83	101	#
1ac4cfb2 NP	102	# Sort all references by the starting position in text
	103	#
	104	sorted_matches = sorted(chain(*match_iterators), key=lambda m: m.start())
d82b1e83	105	for m in sorted_matches:
d74b0d31	106	#
d82b1e83	107	# Include any text prior to match as a normal text node.
d74b0d31 JC	108	#
	109	if m.start() > done:
	110	repl.append(nodes.Text(t[done:m.start()]))
1ac4cfb2	111
d74b0d31	112	#
1ac4cfb2 NP	113	# Call the function associated with the regex that matched this text and
1ac4cfb2 NP	114	# append its return to the text
d74b0d31	115	#
1ac4cfb2 NP	116	repl.append(markup_func[m.re](docname, app, m))
1ac4cfb2 NP	117
d74b0d31 JC	118	done = m.end()
	119	if done < len(t):
	120	repl.append(nodes.Text(t[done:]))
	121	return repl
	122
1ac4cfb2	123	#
c51d9b04 NP	124	# In sphinx3 we can cross-reference to C macro and function, each one with its
c51d9b04 NP	125	# own C role, but both match the same regex, so we try both.
1ac4cfb2	126	#
c51d9b04 NP	127	def markup_func_ref_sphinx3(docname, app, match):
	128	class_str = ['c-func', 'c-macro']
	129	reftype_str = ['function', 'macro']
	130
	131	cdom = app.env.domains['c']
	132	#
	133	# Go through the dance of getting an xref out of the C domain
	134	#
fb568273	135	base_target = match.group(2)
c51d9b04 NP	136	target_text = nodes.Text(match.group(0))
c51d9b04 NP	137	xref = None
fb568273 NP	138	possible_targets = [base_target]
	139	# Check if this document has a namespace, and if so, try
	140	# cross-referencing inside it first.
	141	if c_namespace:
	142	possible_targets.insert(0, c_namespace + "." + base_target)
c51d9b04	143
fb568273 NP	144	if base_target not in Skipnames:
	145	for target in possible_targets:
	146	if target not in Skipfuncs:
	147	for class_s, reftype_s in zip(class_str, reftype_str):
	148	lit_text = nodes.literal(classes=['xref', 'c', class_s])
	149	lit_text += target_text
	150	pxref = addnodes.pending_xref('', refdomain = 'c',
	151	reftype = reftype_s,
	152	reftarget = target, modname = None,
	153	classname = None)
	154	#
	155	# XXX The Latex builder will throw NoUri exceptions here,
	156	# work around that by ignoring them.
	157	#
	158	try:
	159	xref = cdom.resolve_xref(app.env, docname, app.builder,
	160	reftype_s, target, pxref,
	161	lit_text)
	162	except NoUri:
	163	xref = None
	164
	165	if xref:
	166	return xref
c51d9b04 NP	167
	168	return target_text
	169
1ac4cfb2	170	def markup_c_ref(docname, app, match):
c51d9b04 NP	171	class_str = {# Sphinx 2 only
c51d9b04 NP	172	RE_function: 'c-func',
06dc65b0 NP	173	RE_generic_type: 'c-type',
	174	# Sphinx 3+ only
	175	RE_struct: 'c-struct',
	176	RE_union: 'c-union',
	177	RE_enum: 'c-enum',
	178	RE_typedef: 'c-type',
	179	}
c51d9b04 NP	180	reftype_str = {# Sphinx 2 only
c51d9b04 NP	181	RE_function: 'function',
06dc65b0 NP	182	RE_generic_type: 'type',
	183	# Sphinx 3+ only
	184	RE_struct: 'struct',
	185	RE_union: 'union',
	186	RE_enum: 'enum',
	187	RE_typedef: 'type',
	188	}
1ac4cfb2 NP	189
	190	cdom = app.env.domains['c']
	191	#
	192	# Go through the dance of getting an xref out of the C domain
	193	#
fb568273	194	base_target = match.group(2)
1ac4cfb2 NP	195	target_text = nodes.Text(match.group(0))
1ac4cfb2 NP	196	xref = None
fb568273 NP	197	possible_targets = [base_target]
	198	# Check if this document has a namespace, and if so, try
	199	# cross-referencing inside it first.
	200	if c_namespace:
	201	possible_targets.insert(0, c_namespace + "." + base_target)
	202
	203	if base_target not in Skipnames:
	204	for target in possible_targets:
	205	if not (match.re == RE_function and target in Skipfuncs):
	206	lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]])
	207	lit_text += target_text
	208	pxref = addnodes.pending_xref('', refdomain = 'c',
	209	reftype = reftype_str[match.re],
	210	reftarget = target, modname = None,
	211	classname = None)
	212	#
	213	# XXX The Latex builder will throw NoUri exceptions here,
	214	# work around that by ignoring them.
	215	#
	216	try:
	217	xref = cdom.resolve_xref(app.env, docname, app.builder,
	218	reftype_str[match.re], target, pxref,
	219	lit_text)
	220	except NoUri:
	221	xref = None
	222
	223	if xref:
	224	return xref
	225
	226	return target_text
1ac4cfb2	227
d18b0178 NP	228	#
	229	# Try to replace a documentation reference of the form Documentation/... with a
	230	# cross reference to that page
	231	#
	232	def markup_doc_ref(docname, app, match):
	233	stddom = app.env.domains['std']
	234	#
	235	# Go through the dance of getting an xref out of the std domain
	236	#
ea1d8389 NP	237	absolute = match.group(1)
	238	target = match.group(2)
	239	if absolute:
	240	target = "/" + target
d18b0178 NP	241	xref = None
	242	pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc',
	243	reftarget = target, modname = None,
	244	classname = None, refexplicit = False)
	245	#
	246	# XXX The Latex builder will throw NoUri exceptions here,
	247	# work around that by ignoring them.
	248	#
	249	try:
	250	xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc',
	251	target, pxref, None)
	252	except NoUri:
	253	xref = None
	254	#
	255	# Return the xref if we got it; otherwise just return the plain text.
	256	#
	257	if xref:
	258	return xref
	259	else:
	260	return nodes.Text(match.group(0))
	261
fb568273 NP	262	def get_c_namespace(app, docname):
	263	source = app.env.doc2path(docname)
	264	with open(source) as f:
	265	for l in f:
	266	match = RE_namespace.search(l)
	267	if match:
	268	return match.group(1)
	269	return ''
	270
d74b0d31	271	def auto_markup(app, doctree, name):
fb568273 NP	272	global c_namespace
fb568273 NP	273	c_namespace = get_c_namespace(app, name)
7cc4c092 JC	274	def text_but_not_a_reference(node):
	275	# The nodes.literal test catches ``literal text``, its purpose is to
	276	# avoid adding cross-references to functions that have been explicitly
	277	# marked with cc:func:.
	278	if not isinstance(node, nodes.Text) or isinstance(node.parent, nodes.literal):
	279	return False
	280
	281	child_of_reference = False
	282	parent = node.parent
	283	while parent:
	284	if isinstance(parent, nodes.Referential):
	285	child_of_reference = True
	286	break
	287	parent = parent.parent
	288	return not child_of_reference
	289
d74b0d31 JC	290	#
	291	# This loop could eventually be improved on. Someday maybe we
	292	# want a proper tree traversal with a lot of awareness of which
	293	# kinds of nodes to prune. But this works well for now.
	294	#
d74b0d31	295	for para in doctree.traverse(nodes.paragraph):
7cc4c092 JC	296	for node in para.traverse(condition=text_but_not_a_reference):
7cc4c092 JC	297	node.parent.replace(node, markup_refs(name, app, node))
d74b0d31 JC	298
	299	def setup(app):
	300	app.connect('doctree-resolved', auto_markup)
	301	return {
	302	'parallel_read_safe': True,
	303	'parallel_write_safe': True,
	304	}