如何在 Windows 中使用 sphinx 文档生成器？

Question

我想使用 sphinx 文档生成器创建一个站点。但是我的机器是windows。我找不到足够的 Windows 资源。如果有人可以建议我在 Windows 中实现 sphinx 的方法将是一个很大的帮助。

谢谢。

Answer 1

Sphinx 在 Windows 上运行良好。要开始使用，请转到 Quickstart 教程并按照说明进行操作。我要添加的一件事是确保您对询问是否要分离构建和源文件夹的问题回答“y”。这将使以后的事情变得更简单。

如果你想使用 apidoc（我想你会这样做），那么可以使用 Python 安装的 Scripts 文件夹中的命令行工具。或者您可以编写自己的脚本。下面是我为获取某些目标模块的 .rst 文件而写的：

files = [u'C:\\Work\\Scripts\\Grapher\\both_pyplot.py',
         u'C:\\Work\\Scripts\\Grapher\\colors_pyplot.py',
         u'C:\\Work\\Scripts\\Grapher\\dataEditor.pyw',
         u'C:\\Work\\Scripts\\Grapher\\grapher.pyw']

for d in ('pyfiles', 'rst_temp'):
    try:
        shutil.rmtree(d)
    except WindowsError:
        pass
    os.mkdir(d)

#copy, rename .pyw files to .py so sphinx will pick them up
for fn in files:
    fn2 = fn
    if fn.lower().endswith('.pyw'):
        fn2 = fn[:-1]
    shutil.copy2(fn, os.path.join('pyfiles', os.path.basename(fn2)))

#now send to apidoc
lst = [fn, '-o', 'rst_temp', 'pyfiles']  
from sphinx.apidoc import main
main(lst)


msg = ('Now copy the rst files you want documentation for from the '
      '"rst_temp" dir to the the "source" dir, edit the index.html file '
      'in the "source" dir, and run builder.py')
print msg 

apidoc 扩展名无法识别 .pyw 文件，因此此脚本将目标模块复制到一个临时位置并使用 .py 扩展名重命名它们，以便 apidoc 可以使用它们。

要构建您的项目，您可以运行项目文件夹中的 make.bat 文件（在运行快速入门时创建），或者您可以编写自己的脚本。这是一个示例（builder.py）：

import sys, os
fn = __file__

sys.path.append(os.path.normpath('C:\\Work\\Scripts\\Grapher'))

lst = [fn, '-b', 'html', 'source', 'build']

from sphinx import main
main(lst)