python - 从 setup.py 安装 sphinx 编译文档

Question

我想安装一些使用 sphinx 制作的 HTML 在线文档(从 rSt 编译而来)与 python 代码一起放入站点包中。我想使用 setup.py 来实现这一点。

更具体地说，我想将 *.rst 文件编译为 HTML，然后在用户输入 python setup 时将其从 setup.py 文件复制到 site-package 中。 py 安装。

有人知道怎么做吗？我查看了 sphinx 和 setuptools 文档，但找不到信息。

我想这样做的原因是我的包是一个GUI工具，而HTML是它的在线帮助。它显示在 GUI 的内部浏览器中。

Answer 1

如前所述，您需要一个 MANIFEST.in 文件来包含文档目录:

recursive-include docs *

现在，在您的 setup.py 中，您可以通过编程方式从 *.rst 文件生成 sphinx 文档。

以下示例介绍了如何在运行 python setup.py install 时自动执行此操作:

from distutils.core import setup

# set dependencies, we need sphinx to build doc
dependencies = ['sphinx']

setup(
    name='my_package'
    # rest of your setup
)

# auto-generate documentation
import sphinx

# automatically build html documentation
# For example:
#   format = 'html'
#   sphinx-src-dir = './doc'
#   sphinx-build-dir = './doc/build'
sphinx.build_main(['setup.py', '-b', '<format>', '<sphinx-src-dir>', '<sphinx-build-dir>'])

像这样，您可以根据需要运行 sphinx-build ( Documentation )。

注意:添加 Custom command 可能是个好主意。到您的 setup.py 用于分离文档生成(例如 python setup.py make_doc [params])和安装例程(python setup.py install )。这样用户就可以轻松提供参数format、sphinx-src-dir和sphinx-build-dir。