Python2.7.13+Sphinx1.7：sphinx-apidoc忽略src目录及重命名包名方法

嗨，针对你用Sphinx 1.7和Python 2.7.13自动生成文档时遇到的两个问题，我给你整理了具体的解决步骤，完全适配你的项目结构（myPythonProject → docs → _build/apidocs等目录）：

有两种靠谱的方式可以实现，推荐优先用第一种，避免生成多余的rst文件：

• 命令行直接排除：在docs目录下运行sphinx-apidoc时，通过--exclude参数指定要忽略的src目录。示例命令如下：

  sphinx-apidoc -o _build/apidocs ../myPythonProject --exclude ../myPythonProject/src
  

  这样sphinx-apidoc会直接跳过src目录，不会生成任何和它相关的rst文件，最干净高效。

• 在conf.py中配置排除规则：如果已经生成了包含src的rst文件，或者想做全局排除，可以在docs/conf.py里修改exclude_patterns列表，添加src相关的路径：

  exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_build/apidocs/src*']
  

  这样在生成HTML文档时，Sphinx会自动跳过匹配这些路径的内容。

如果你想把文档里显示的包名（比如默认的myPythonProject package）改成自定义名称，有两种实用方法：

方法一：自定义apidoc模板（推荐，一劳永逸） #

这种方法可以让每次生成rst文件时自动用你想要的包名，不用手动修改：

1. 先找到Sphinx自带的apidoc模板文件：在Python 2.7的site-packages目录下，路径大概是sphinx/ext/apidoc/templates/apidoc，里面有package.rst_t和module.rst_t两个模板文件。
2. 在你的docs/_templates目录下创建一个apidoc子目录，把上面找到的两个模板文件复制进去。
3. 打开package.rst_t，找到标题行（默认是{{ fullname }} package），修改成你想要的名称。比如：
   • 如果想把myPythonProject替换成My Awesome Python Project，可以改成：

     {{ fullname.replace('myPythonProject', 'My Awesome Python Project') }} package
     

   • 或者直接写死固定标题：

     My Awesome Python Project package
     

4. 运行sphinx-apidoc时，加上--templatedir参数指定你的自定义模板目录：

   sphinx-apidoc -o _build/apidocs ../myPythonProject --templatedir _templates/apidoc --exclude ../myPythonProject/src
   

   这样生成的rst文件里的包标题就会是你自定义的内容了。

方法二：手动修改生成的rst文件（临时应急） #

如果只是临时改一次，不想折腾模板，可以直接修改_build/apidocs目录下生成的rst文件：

• 找到主包对应的rst文件（比如myPythonProject.rst），把开头的标题myPythonProject package改成你想要的名称，比如My Custom Project。
• 注意：这种方法的缺点是每次重新运行sphinx-apidoc时，修改的内容会被覆盖，需要重新修改。

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