如何解决reStructuredText和Sphinx中重复目标名称的问题

解决方案 #

Sphinx中.. _xxx:格式的显式目标名是全局唯一的，跨文件重复定义就会触发上述警告，可通过以下两种方案解决：

• 方案一：给目标名加上所属类的唯一前缀
  把class_MyNamespace__MyClassOne.rst.inc里的.. _attr_private_int:改为.. _MyClassOne_attr_private_int:，同步把表格里的引用改为MyClassOne_attr_private_int_；同理把class_MyNamespace__MyClassTwo.rst.inc里的对应标签改为.. _MyClassTwo_attr_private_int:，引用改为MyClassTwo_attr_private_int_即可。如果是工具自动生成的RST文件，直接修改生成脚本，自动给属性、方法的目标名拼接所属类/命名空间前缀即可。
• 方案二：使用匿名隐式链接
  如果你不需要在其他文件单独引用该属性，可以把引用末尾的单下划线改为双下划线，同时删掉显式的.. _attr_private_int:定义，直接写成：

  Attributes Summary
  ==================
  +-----------------------+--------------------------------------------+
  | `attr_private_int`__ | attr_private_int: this is an integer attr. |
  +-----------------------+--------------------------------------------+
  
  Attribute Documentation
  =======================
  `attr_private_int`__
      attr_private_int: this is an integer attr.
  

  双下划线的隐式链接不需要全局唯一，不会触发冲突。

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