1 # SPDX-License-Identifier: MIT
3 # Copyright (c) 2020 Philippe Proulx <pproulx@efficios.com>
5 # This file is a Sphinx extension which adds the following roles:
8 # A typical manual page reference, like `grep(1)`.
14 # This role creates a simple inline literal node with the role's
15 # text if it's not a Babeltrace 2 manual page reference, or an
16 # external link to the corresponding online manual page (on
17 # `babeltrace.org`) with the appropriate project's version
18 # (`version` configuration entry) otherwise.
21 # An external link with an URL in which a specific placeholder is
22 # replaced with the project's version.
24 # The role's text follows the typical external link format, for
27 # Link text <https://example.com/>
29 # Any `@ver@` in the URL is replaced with the project's version
30 # (`version` configuration entry).
34 # :bt2link:`libbabeltrace2 <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`
44 bt2_version
, name
, rawtext
, text
, lineno
, inliner
, options
=None, content
=None
46 # match a manual page reference
47 m
= re
.match(r
"^([a-zA-Z0-9_.:-]+)\(([a-zA-Z0-9]+)\)$", text
)
50 msg
= "Cannot parse manual page reference `{}`".format(text
)
51 inliner
.reporter
.severe(msg
, line
=lineno
)
52 return [inliner
.problematic(rawtext
, rawtext
, msg
)], [msg
]
54 # matched manual page and volume
58 # create nodes: `ret_node` is the node to return
59 page_node
= docutils
.nodes
.strong(rawtext
, page
)
60 vol_node
= docutils
.nodes
.inline(rawtext
, "({})".format(vol
))
61 man_node
= docutils
.nodes
.inline(rawtext
, "", page_node
, vol_node
)
62 ret_node
= docutils
.nodes
.literal(rawtext
, "", man_node
)
64 if page
.startswith("babeltrace2"):
65 # Babeltrace 2 manual page: wrap `ret_node` with an external
67 url_tmpl
= "https://babeltrace.org/docs/v{ver}/man{vol}/{page}.{vol}/"
68 url
= url_tmpl
.format(ver
=bt2_version
, vol
=vol
, page
=page
)
69 ret_node
= docutils
.nodes
.reference(
70 rawtext
, "", ret_node
, internal
=False, refuri
=url
77 bt2_version
, name
, rawtext
, text
, lineno
, inliner
, options
=None, content
=None
79 # match link text and URL
80 m
= re
.match(r
"^([^<]+) <([^>]+)>$", text
)
83 msg
= "Cannot parse link template `{}`".format(text
)
84 inliner
.reporter
.severe(msg
, line
=lineno
)
85 return [inliner
.problematic(rawtext
, rawtext
, msg
)], [msg
]
87 link_text
= m
.group(1)
89 # replace `@ver@` with the project's version
90 url
= m
.group(2).replace("@ver@", bt2_version
)
92 # create and return an external link node
93 node
= docutils
.nodes
.reference(rawtext
, link_text
, internal
=False, refuri
=url
)
98 # add the extension's roles; the role functions above expect the
99 # project's version as their first parameter
100 app
.add_role("bt2man", functools
.partial(_bt2man_role
, app
.config
.version
))
101 app
.add_role("bt2link", functools
.partial(_bt2link_role
, app
.config
.version
))
105 app
.connect("builder-inited", _add_roles
)
107 "version": app
.config
.version
,
108 "parallel_read_safe": True,
This page took 0.033786 seconds and 5 git commands to generate.