如何在Sphinx中正确显示Python文档字符串中的竖线字符

问题根源 #

Sphinx默认会对文档字符串中的纯文本进行空格压缩和换行合并，导致ASCII艺术形式的目录结构丢失原有排版。

可行解决方案 #

• 用代码块包裹目录结构：在Python文档字符串里，把目录结构用三重反引号包裹，最好指定语言为text，确保Sphinx将其识别为纯文本代码块，保留所有空格和换行。示例代码：

def generate_output():
    """生成指定结构的输出目录

    输出目录结构示例：
    ```text
    output_dir
    │   categories.yaml
    │
    └───images
    │       filename1.png
    │       filename1.png
    │       ...
    │
    └───masks
            filename1.png
            filename2.png
            ...
    ```
    """
    # 函数逻辑
    pass

• 检查Sphinx配置：确保项目的conf.py中启用了sphinx.ext.autodoc扩展，该扩展负责正确解析文档字符串中的代码块格式；同时避免配置会干扰文本排版的选项。
• 使用raw指令（备选）：如果代码块方式不生效，可以用.. raw:: html包裹目录结构并添加HTML换行和空格样式，但这种方式依赖HTML渲染，通用性不如代码块。

验证效果 #

重新生成Sphinx文档后，目录结构会以带格式的代码块形式展示，不再被压缩为单行。

内容的提问来源于stack exchange，提问作者Mario Namtao Shianti Larcher