如何阻止Sphinx对RST文本进行自动断字？

刚好之前踩过这个坑！在Sphinx搭配reStructuredText的场景下，要避免文本被自动拆分成带连字符的断字（比如把"sentence"拆成"sent-ence"），得根据你的需求（全局/局部）和输出格式（HTML/PDF）来选对应的方法，下面给你逐一说明：

一、全局禁用断字（所有文档生效） #

1. 针对HTML输出 #

编辑项目根目录下的conf.py，添加docutils的配置项，直接关闭自动换行和断字逻辑：

# 在conf.py中加入以下配置
docutils_conf = {
    'disable_auto_line_break': True,
    'word_wrap': False,
    'hyphenation': False
}

这样docutils在处理RST文本时，就不会为了适配行宽而拆分长单词了。

2. 针对PDF输出（基于LaTeX） #

如果是生成PDF文档，断字是由LaTeX引擎处理的，你需要在conf.py的LaTeX配置里禁用全局断字：

latex_elements = {
    # 通过LaTeX包禁用自动断字
    'preamble': r'''
        \usepackage[none]{hyphenat}
        \sloppy
    '''
}

hyphenat包的none选项会完全关闭断字功能，\sloppy则会让LaTeX自动调整单词间距，尽量避免换行时拆分单词。

二、局部禁用断字（仅针对特定文本） #

如果不想全局修改，只想让某一段或某几个单词不被断字，可以用下面几种方式：

• HTML输出专属：用raw指令直接输出HTML，绕开docutils的断字处理：

  .. raw:: html
  
      This is my long sentence that won't get hyphenated.
  

• PDF输出专属：同样用raw指令，插入LaTeX的无断字命令：

  .. raw:: latex
  
      \nohyphens{This is my long sentence that won't get hyphenated.}
  

• 通用方案（HTML/PDF都适配）：先定义一个自定义角色，再配合样式实现：

  1. 在RST文档开头添加角色定义：

     .. role:: nohyphen
        :class: no-hyphen
     

  2. 针对HTML，在项目的自定义CSS文件中添加样式：

     .no-hyphen {
         hyphens: none;
     }
     

  3. 针对PDF，在conf.py的LaTeX预导言中添加样式映射：

     latex_elements = {
         'preamble': r'''
             \usepackage[none]{hyphenat}
             \newcommand{\nohyphen}[1]{\nohyphens{#1}}
         '''
     }
     

  4. 最后在文本中使用这个角色：

     :nohyphen:`This is my long sentence that won't get hyphenated.`
     

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