我创建了一个超小型扩展来添加角色"图标"；在我的医生。这个想法是写下以下内容：
I'm a folder :icon:`fa fa-folder`
我在网上修改了一些代码，并提出了以下内容：
from docutils import nodes
def icon_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
"""add inline icons
Returns 2 part tuple containing list of nodes to insert into the
document and a list of system messages. Both are allowed to be
empty.
:param name: The role name used in the document.
:param rawtext: The entire markup snippet, with role.
:param text: The text marked with the role.
:param lineno: The line number where rawtext appears in the input.
:param inliner: The inliner instance that called us.
:param options: Directive options for customization.
:param content: The directive content for customization.
"""
node =nodes.reference()
html = f"<i class="{text}"></i>"
node = nodes.raw('', html, format='html')
return [node], []
def setup(app):
"""Install the plugin.
:param app: Sphinx application context.
"""
app.add_role('icon', icon_role)
return
问题是在我的pdf输出中没有考虑到这个角色，它仍然是空白的。我是否应该添加额外的代码，使其在乳胶中也能工作？
基于我在sphinx-contrib组织中的发现，特别是在聪明的youtube sphinx扩展中，我编码了一个自定义node，它将为HTML输出创建<i>标记，并为latex输出创建粗体输出。当然，在乳胶中显示图标需要更多的工作，但这与此无关。
我把代码留在这里给任何感兴趣的人。
# -*- coding: utf-8 -*-
from docutils import nodes
class icon(nodes.General, nodes.Element):
"""A general node class that will be used in setup"""
pass
def depart_icon_node(self, node):
"""Empty depart function, everything is handled in visit functions"""
pass
def visit_icon_node_html(self, node):
"""entry point of the html node. we simply create a <i> tag"""
icon = node["icon"]
self.body.append(f"<i class="{icon}"></i>")
return
def visit_icon_node_latex(self, node):
"""
entry point of the html node. we simply write down the text in bold.
See the linked repository for more complex macros and how to set them up in 'preamble'
"""
icon = node["icon"]
self.body.append("\textbf{%s}" %(icon))
return
def visit_icon_node_unsuported(self, node):
"""raise error when the requested output is not supported"""
self.builder.warn(f'unsupported output format (node skipped)')
raise nodes.SkipNode
_NODE_VISITORS = {
'html': (visit_icon_node_html, depart_icon_node),
'latex': (visit_icon_node_latex, depart_icon_node),
'man': (visit_icon_node_unsuported, None), # don't need depart function because I raise an error
'texinfo': (visit_icon_node_unsuported, None), # same
'text': (visit_icon_node_unsuported, None) #same
}
def icon_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
"""add inline icons"""
node = icon(icon=text)
return [node], []
def setup(app):
"""Install the plugin.
:param app: Sphinx application context.
"""
app.add_node(icon, **_NODE_VISITORS)
app.add_role('icon', icon_role)
return