如何让Sphinx LaTeX构建器为sphinxincludegraphics添加Alt文本以生成PDF UA文档？

问题背景 #

我负责从RST生成符合PDF UA标准的无障碍文档，原本计划通过DocumentMetadata启用标记功能，借助标题或:alt:属性实现目标，但找不到把Alt文本插入LaTeX的方法。

期望生成的LaTeX代码：

\begin{figure}[H]
\centering
\capstart
\noindent\sphinxincludegraphics[alt={a screenshot of foo},width=0.800\linewidth]{{foo}.png}
\caption{A screenshot of foo}\label{\detokenize{foo:id10}}\end{figure}

\noindent\sphinxincludegraphics[alt={a screenshot of foo}]{{foo}.png}

对应的RST示例代码：

.. figure:: ../images/foo.png
    :width: 80%
    :align: center
    
    A screenshot of foo


.. image:: ../images/foo.png
    :alt: A screenshot of foo

可行实现方法 #

1. 定制Sphinx LaTeX模板 #

Sphinx默认的LaTeX输出模板不会传递图片的alt属性，需要修改模板逻辑：

• 可在项目的_templates/latex目录自定义模板，或修改Sphinx内置的sphinx.sty文件
• 重写图片生成的代码块：
  • 对于独立.. image::指令：提取:alt:属性值，添加到\sphinxincludegraphics的alt参数中
  • 对于.. figure::指令：将图题文本作为alt值传入，符合PDF UA对figure元素的无障碍要求

2. 自定义Sphinx扩展注入Alt文本 #

编写简单的Sphinx扩展，在文档树解析阶段给图片节点添加alt元数据，供LaTeX模板读取：

from docutils.nodes import image, figure

def process_images(app, doctree, docname):
    # 处理独立图片节点
    for node in doctree.traverse(image):
        alt_text = node.get('alt', '')
        node['latex_alt'] = alt_text
    # 处理figure中的图片，用图题作为alt文本
    for node in doctree.traverse(figure):
        caption_node = node.next_node('caption')
        if caption_node:
            alt_text = caption_node.astext()
            for img_node in node.traverse(image):
                img_node['latex_alt'] = alt_text

def setup(app):
    app.connect('doctree-resolved', process_images)

将上述代码保存为项目中的accessibility_ext.py，然后在conf.py中添加extensions = ['accessibility_ext']启用扩展。

之后修改LaTeX模板中的图片生成代码，例如将原模板中的：

\sphinxincludegraphics[{{options}}]{{{{filename}}}}

替换为：

\sphinxincludegraphics[alt={{{latex_alt}}},{{options}}]{{{{filename}}}}

3. 配置Sphinx启用PDF UA支持 #

在项目的conf.py中添加LaTeX配置，确保生成的PDF符合PDF UA标准：

latex_elements = {
    'preamble': r'''
        \usepackage[tagged]{accessibility}
        \usepackage{hyperref}
        \hypersetup{
            pdfua=true,
            pdfstandard=PDF/A-2b,
            colorlinks=true
        }
    '''
}
latex_documents = [
    (master_doc, 'your_project.tex', '项目名称', '作者', 'manual'),
]

这里的accessibility包配合hyperref的pdfua=true参数，能确保文档的无障碍标记被正确识别。

内容的提问来源于stack exchange，提问作者Niklas Maurer