将外部文档包含到 Sphinx 项目中

Question

我们在 SVN 中使用 Sphinx 维护了相当大的文档。

作为生成输出的一部分，我们希望包含相关 Python 模块的发行说明作为主要内容（而不是超链接！）。外部模块的发行说明也在 SVN 中维护。是否有一些类似 Sphinx 的方法可以从其他（SVN）来源获取部分文档？好吧，使用 SVN 外部是解决问题的一种方法，但也许不是最明智的方法......还有更好的选择吗？

Answer 1

我能想到的两个选项是：

1. 将 svn:externals 链接添加到远程项目（您已经了解）。
2. 使用自定义指令扩展 Sphinx 以包含来自远程 subversion 存储库的文件。

我不是 Sphinx 内部的专家，但能够拼凑出一个快速扩展，该扩展嵌入来自远程颠覆存储库的文件。

该扩展添加了一个 svninclude 指令，该指令采用 1 个参数，即您的文档所在存储库的 URL。它将这个存储库检出到位于项目根目录中的临时目录 _svncache 中，然后继续读取每个文件的内容并将它们插入到解析器的状态机中。

以下是 svninclude.py 扩展的代码。它过于简单化，目前没有错误检查。如果您打算实现此功能，请告诉我，如果您遇到困难，我可以提供一些额外的提示：

import os, re, subprocess, sys
from docutils import nodes, statemachine
from docutils.parsers.rst import directives
from sphinx.util.compat import Directive, directive_dwim

class SvnInclude(Directive):

    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = False

    def _setup_repo(self, repo):
        env = self.state.document.settings.env
        path = os.path.normpath(env.doc2path(env.docname, base=None))
        cache = os.path.join(os.path.dirname(path), '_svncache')
        root = os.path.join(cache, re.sub('[\W\-]+', '_', repo))
        if not os.path.exists(root):
            os.makedirs(root)
        subprocess.call(['svn', 'co', repo, root])
        return root

    def run(self):
        root = self._setup_repo(self.arguments[0])
        for path in self.content:
            data = open(os.path.join(root, path), 'rb').read()
            lines = statemachine.string2lines(data)
            self.state_machine.insert_input(lines, path)
        return []

def setup(app):
    app.add_directive('svninclude', directive_dwim(SvnInclude))

以下是您要包含在 index.rst（或其他文件）中的标记示例：

.. svninclude:: http://svn.domain.com/svn/project

    one.rst
    doc/two.rst

其中路径 one.rst 和 doc/two.rst 相对于 subversion url，例如 http://svn.domain.com/svn/项目/one.rst。

您当然希望打包 svninclude.py 并将其安装在您的 Python 路径中。以下是我对其进行的测试：

1. 将 'svninclude' 添加到 source/conf.py 中的 extensions 列表。
2. 将 svninclude.py 放置在项目根目录中。

然后跑：

% PYTHONPATH=. sphinx-build -b html ./source ./build