如何让sphinx-apidoc、doctest与-W选项协同正常工作？

方案一：调整流水线顺序并修正toctree引用 #

通过先生成API文档，再确保所有自动生成的rst文件被正确包含，消除警告：

1. 先运行sphinx-apidoc生成API文档

   sphinx-apidoc -f -o docs/ src/my_package
   

   这会生成modules.rst和my_package.rst（若有子模块，还会生成对应子模块的rst文件）。

2. 修改index.rst的toctree配置
   将原来的my_package替换为modules，示例如下：

   .. toctree::
      :maxdepth: 2
      :caption: Contents:
   
      modules
   

   modules.rst内部已包含指向my_package.rst的toctree，这样既保证API文档能被正确渲染，又解决了modules.rst未被包含的警告。

3. 运行带-W参数的doctest

   sphinx-build -W -b doctest -d docs/build/doctrees docs docs/build/doctest
   

4. 运行带-W参数的HTML构建

   sphinx-build -W -b html -d docs/build/doctrees docs docs/build/html
   

方案二：自定义apidoc的TOC文件名（保留原有index.rst结构） #

如果不想改动index.rst里原有的my_package引用，可通过apidoc的--tocfile参数生成匹配的TOC文件：

1. 用--tocfile生成自定义TOC文件

   sphinx-apidoc -f --tocfile my_package -o docs/ src/my_package
   

   这会直接生成my_package.rst作为TOC文件（替代默认的modules.rst），内部包含所有子模块的引用，正好匹配你index.rst里原有的toctree项。

2. 运行带-W参数的doctest

   sphinx-build -W -b doctest -d docs/build/doctrees docs docs/build/doctest
   

3. 运行带-W参数的HTML构建

   sphinx-build -W -b html -d docs/build/doctrees docs docs/build/html
   

以上两种方案都能让两个sphinx-build调用正常使用-W参数，同时自动生成完整的API文档。

内容的提问来源于stack exchange，提问作者Mr-Pepe