如何使用doxygenclass指令为重载类模板生成Sphinx文档

解决方案 #

你遇到的问题是Breathe插件（Sphinx用于解析Doxygen输出的依赖组件）对C++模板偏特化的匹配逻辑对签名格式要求严格，且Doxygen默认不会导出偏特化类的信息，按以下步骤操作即可解决：

1. 修改Doxygen配置
   打开你的Doxyfile配置文件，找到TEMPLATE_SPECIALIZATIONS配置项，将值改为YES，之后重新运行Doxygen生成XML格式的输出，确保偏特化类的信息被写入到XML文件中。
2. 调整rst文件的类签名写法
   Breathe匹配偏特化类时，需要签名和Doxygen生成的XML中<compoundname>标签的内容完全一致，绝大多数场景下只要在尖括号内侧加上空格即可匹配，调整后的rst内容如下：

.. _dummy class:

Dummy Class
===========

.. doxygenclass:: X::A
   :members:
   :protected-members:
   :private-members:

.. doxygenclass:: X::B
   :members:
   :protected-members:
   :private-members:

.. doxygenclass:: X::B< T, 1 >
   :members:
   :protected-members:
   :private-members:

如果按照上述写法仍然无法识别，可以打开Doxygen输出的XML目录，找到偏特化类对应的XML文件（命名通常为classX_1_1B_xxxxxx.xml格式），查看文件内<compoundname>标签的文本内容，完全按照该内容填写到doxygenclass指令后即可。
如果使用的Breathe版本低于4.30.0，建议升级到最新稳定版，旧版本不支持模板偏特化的解析。

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