为Sphinx网站自定义PyBTeX样式失败，请求技术协助

我需要在Sphinx网站中添加参考文献列表，因此编写了自定义PyBTeX样式来控制作者显示数量、格式（如加粗）、DOI可见性等，但配置后参考文献完全不显示。已编写custom.py样式文件并在conf.py中导入，通过RST文档的.. bibliography:: bib/refs.bib调用，不确定样式代码是否存在问题，求解决。

自定义样式文件（custom.py） #

from sphinxcontrib.bibtex.style.referencing import BaseReferenceStyle

class CustomStyle(BaseReferenceStyle):
    def role_names(self):
        return ["cite"]

    def format_citation(self, key, entry, label=None):
        author = entry.persons.get("author", [])
        if author:
            last_name = author[0].last_names[0].upper()
        else:
            last_name = "UNKNOWN"
        year = entry.fields.get("year", "n.d.")
        return f"{last_name} [{year[::-1]}]"

    def format_bibliography_entry(self, key, entry, label=None):
        author = entry.persons.get("author", [])
        if author:
            author_str = " & ".join([p.last_names[0].upper() for p in author])
        else:
            author_str = "UNKNOWN"

        title = entry.fields.get("title", "No Title")
        journal = entry.fields.get("journal", "")
        year = entry.fields.get("year", "n.d.")[::-1]

        parts = [
            f"🎉 {author_str}",
            f"<i>{title}</i>",
            journal,
            f"[{year}]"
        ]
        return " – ".join([p for p in parts if p])

配置文件（conf.py） #

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent / "_ext"))

import my_pybtex_styles.funky_format

extensions = [
    "sphinx_favicon",
    "sphinxcontrib.bibtex",
    "news",
]

bibtex_bibfiles = ["bib/refs.bib"]
bibtex_default_style = "funky_format"
...

问题分析与解决方案 #

1. 样式基类继承错误 #

当前CustomStyle仅继承了BaseReferenceStyle，这个类仅负责文中引用标记的格式（比如[Smith 2023]），但参考文献列表的渲染需要单独继承BaseBibliographyStyle类。sphinxcontrib.bibtex要求引用样式和参考文献样式分开定义。

2. 样式名称与配置不匹配 #

自定义文件名为custom.py，但conf.py中指定的bibtex_default_style = "funky_format"，且导入的是my_pybtex_styles.funky_format，路径和样式名称完全不匹配，导致Sphinx无法找到自定义样式。

3. 缺少样式注册步骤 #

自定义样式需要通过setup函数注册到Sphinx中，否则sphinxcontrib.bibtex无法识别。

修正后的自定义样式文件（custom.py） #

from sphinxcontrib.bibtex.style.bibliography import BaseBibliographyStyle
from sphinxcontrib.bibtex.style.referencing import BaseReferenceStyle
from sphinxcontrib.bibtex.style.template import (
    author_or_editor,
    join,
    names,
    field,
    optional,
    sentence,
    tag,
)

# 定义参考文献列表样式（控制最终列表的格式）
class CustomBibliographyStyle(BaseBibliographyStyle):
    def get_template(self):
        return join(
            # 作者部分：加粗显示，控制分隔符
            sentence(tag("strong")(names(
                author_or_editor,
                sep=", ",
                sep2=" & ",
                last_sep=", & "
            ))),
            # 标题：斜体显示
            tag("em")(field("title")),
            # 期刊（可选）
            optional(field("journal")),
            # 年份
            field("year"),
            # DOI（可选，带前缀）
            optional(field("doi", prefix="DOI: ")),
            sep=" – "
        )

# 定义文中引用样式
class CustomReferenceStyle(BaseReferenceStyle):
    def role_names(self):
        return ["cite"]

    def format_citation(self, key, entry, label=None):
        author = entry.persons.get("author", [])
        last_name = author[0].last_names[0].upper() if author else "UNKNOWN"
        year = entry.fields.get("year", "n.d.")
        # 移除year[::-1]（这会反转年份，比如2023变成3202，若为误写则删除）
        return f"{last_name} [{year}]"

# 注册自定义样式到Sphinx
def setup(app):
    app.add_bibtex_style("custom", CustomBibliographyStyle, CustomReferenceStyle)

修正后的配置文件（conf.py） #

import sys
from pathlib import Path

# 确保自定义样式所在的_ext目录被加入路径
sys.path.insert(0, str(Path(__file__).parent / "_ext"))

extensions = [
    "sphinx_favicon",
    "sphinxcontrib.bibtex",
    "news",
]

bibtex_bibfiles = ["bib/refs.bib"]
# 指定注册的自定义样式名称
bibtex_default_style = "custom"
...

额外说明 #

• 若需要控制作者显示数量（比如只显示前3个作者，后面加“等”），可以在names函数中添加max_names=3参数：names(author_or_editor, max_names=3, sep=", ", ...)
• 若要保留原代码中的特殊符号（如🎉），可以直接加入模板中
• 确保custom.py放在_ext目录下，与conf.py的路径配置一致

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