将外部文档纳入Sphinx项目

Question

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

作为生成输出的一部分，我们希望将相关Python模块的发行说明作为主要内容（而不是超链接！）。 SVN中还维护了外部模块的发行说明。是否有一些Sphinx-ish的方式来从其他（SVN）源文件的部分拉动？好的，使用SVN外部是一种解决问题的方法，但可能不是最聪明的方式......任何更好的选择？

Answer 1

我能想到的两个选项是：

1. 添加svn:externals连接到远程项目（你已经知道）。
2. 使用自定义指令扩展Sphinx以包含来自远程Subversion存储库的文件。

我不是Sphinx内部的专家，但能够拼凑出嵌入远程Subversion存储库文件的快速扩展。

该扩展添加了一个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/project/one.rst。

你当然想打包svninclude.py并将它安装到你的Python路径中。这是我做了测试它：

1. 新增'svninclude'在source/conf.py的extensions列表。
2. 放置在项目根目录下的svninclude.py。

然后跑：

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