Sphinx未正确更新文档
我正在使用Sphinx来为一个Python应用程序编写文档，我用命令sphinx_build_script -b html <path/to/source> <path/to/build>来生成index.html文件。当我修改了文档字符串后，再次使用相同的命令时，发现生成的html内容似乎没有正确更新。
我尝试删除了_build、_sources和构建目录下的所有index文件，但还是没有解决问题。
这是生成的html文件：
PDF报告生成类
:param orientation: 方向可以是竖版或横版。
:param unit: 默认单位是毫米。
:param format: PDF文档的格式（A4、A6、Letter）。
这是源代码：
"""PDF报告生成类
:param orientation: 方向可以是竖版或横版。
:type orientation: 字符。
:param unit: 默认单位是毫米。
:param format: PDF文档的格式（A4、A6、Letter）。
这是一个更新
"""
在连续多次运行构建命令后，似乎html文件只有1/5的几率会更新。
2 个回答
我在开发一个软件包的时候也遇到了同样的问题。如果我更新了文档说明，删除了所有的构建文档，然后重新构建，API文档还是没有变化。为了解决这个问题，我必须重新安装这个软件包，或者以可编辑模式安装它。
pip install -e .
现在重新构建文档应该能显示更新后的文档了。
这不是正确的方法。你应该先使用 apidoc 来生成项目。之后添加的所有类和模块都应该手动加入文档，或者通过再次调用 apidoc 来添加（不过如果你对最初生成的项目进行了自定义，就不应该这样做）。
比如，下面这个指令会把一个新模块及其成员递归地添加到页面中：
.. automodule:: foo.bar
:members:
:undoc-members:
这并不像 JavaDoc 那样自动化，但在某些情况下，至少对文档有一些控制权也是更好的。
另外，最好使用 make html 而不是你现在用的其他方法，因为它会生成一些索引之类的东西。我不太记得具体情况，但我可以肯定的是，当你用 bare Sphinx 脚本时，有些内容是不会生成的。