基于Sphinx Recipe扩展的配料显示问题求助

一、配料未显示的配置遗漏排查 #

• 确认conf.py中已正确注册自定义扩展：检查extensions列表是否包含你的recipe扩展模块（比如仓库中的lumach_sphinx_ext），格式应为extensions = ['lumach_sphinx_ext']
• 验证.rst文件中recipe指令的contains语法：确保格式符合教程规范，例如：

  .. recipe:: 示例食谱
     :contains: 鸡蛋, 面粉, 牛奶
  

• 检查扩展逻辑是否正确处理contains参数：确认RecipeDirective类的run方法中，已将contains的配料值存入self.data["recipe_ingredients"]，且后续渲染/索引逻辑能读取该数据
• 确认IngredientIndex已注册到RecipeDomain：检查RecipeDomain的indices属性是否包含IngredientIndex类，这是生成配料索引的必要前提

二、展示self.data["recipe_ingredients"][name]数据的方法 #

有两种可行方式：

• 直接在指令渲染中输出：在RecipeDirective的run方法里，将配料数据转换为Sphinx节点，比如：

  ingredients = self.options.get('contains', '').split(', ')
  node = nodes.paragraph(text=f"配料: {', '.join(ingredients)}")
  return [node]
  

  这样编译后会在食谱条目下直接显示配料
• 通过自定义模板渲染：修改recipes.html模板，通过域数据访问配料列表，示例代码：

  {% for recipe_name, ingredients in domain.data['recipe_ingredients'].items() %}
    <div class="recipe-item">
      <h3>{{ recipe_name }}</h3>
      <p>配料：{{ ', '.join(ingredients) }}</p>
    </div>
  {% endfor %}
  

三、打印RecipeDomain.indices中的IngredientIndices列表 #

在扩展的setup函数中添加调试逻辑，即可在构建时输出相关内容：

def setup(app):
    app.add_domain(RecipeDomain)
    
    # 构建完成后打印indices列表
    def debug_indices(app, exception):
        if not exception:
            recipe_domain = app.domains['recipe']
            print("RecipeDomain 索引列表:", recipe_domain.indices)
    app.connect('build-finished', debug_indices)

运行sphinx-build命令时，控制台会输出RecipeDomain的索引列表，可确认IngredientIndex是否已正确注册

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