Sphinx生成文档无法显示Python代码块中logger的日志信息

原因 #

Python的logging模块默认日志级别是WARNING，且默认处理器不会将INFO级别的消息输出到标准输出（stdout）。而Sphinx的.. ipython:: python指令仅捕获标准输出内容，因此INFO日志无法被显示。

两种解决方法 #

方法一：快速配置基础日志 #

用logging.basicConfig直接设置日志级别和输出流，修改后的代码块如下：

.. ipython:: python
  
  import logging
  import sys
  # 把日志级别设为INFO，输出定向到标准输出
  logging.basicConfig(level=logging.INFO, stream=sys.stdout)
  logging.info("test logging")
  print("test print")

方法二：手动添加日志处理器 #

如果需要更灵活的配置（比如已有其他日志设置），可以手动给根日志器添加输出到stdout的处理器：

.. ipython:: python
  
  import logging
  import sys
  
  root_logger = logging.getLogger()
  root_logger.setLevel(logging.INFO)
  
  # 创建输出到标准输出的处理器
  stdout_handler = logging.StreamHandler(sys.stdout)
  stdout_handler.setLevel(logging.INFO)
  
  root_logger.addHandler(stdout_handler)
  
  logging.info("test logging")
  print("test print")

效果验证 #

重新构建Sphinx文档后，logging.info的内容就会和print的内容一起显示在文档里了。

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