將外部文檔納入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