स्फिंक्स प्रोजेक्ट

Question

में बाहरी दस्तावेज़ीकरण को शामिल करना हम एसवीएन में स्फिंक्स का उपयोग करके काफी बड़े दस्तावेज बनाए रखते हैं।

जेनरेट आउटपुट के हिस्से के रूप में हम संबंधित पायथन मॉड्यूल के रिलीज नोट्स को प्राथमिक सामग्री (हाइपरलिंक के रूप में नहीं) के रूप में शामिल करना चाहते हैं। एसवीएन में बाह्य मॉड्यूल के रिलीज नोट भी बनाए रखा जाता है। क्या दस्तावेज के कुछ हिस्सों को अन्य (एसवीएन) स्रोतों से खींचने के लिए कुछ स्फिंक्स-आश रास्ता है? ठीक है, एसवीएन बाहरी का उपयोग समस्या को हल करने का एक तरीका है, लेकिन शायद सबसे बुद्धिमान तरीका नहीं ... कोई बेहतर विकल्प?

Answer 1

दो विकल्प मैं के बारे में सोच सकते हैं:

1. दूरस्थ परियोजना (जो आप पहले से ही के बारे में पता) के लिए एक svn:externals लिंक जोड़ें।
2. रिमोट सबवर्जन रिपॉजिटरीज़ से फ़ाइलों को शामिल करने के लिए कस्टम निर्देश के साथ स्फिंक्स बढ़ाएं।

मैं स्फिंक्स आंतरिक पर कोई विशेषज्ञ नहीं हूं लेकिन एक त्वरित विस्तार को एक साथ जोड़ने में सक्षम था जो रिमोट सबवर्जन रिपोजिटरी से फ़ाइलों को एम्बेड करता है।

एक्सटेंशन svninclude निर्देश जोड़ता है जो 1 तर्क लेता है, भंडार का यूआरएल जहां आपके दस्तावेज़ स्थित हैं। यह प्रोजेक्ट रूट में स्थित एक अस्थायी निर्देशिका _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 उपवर्तन यूआरएल के सापेक्ष हैं, उदाहरण के लिए http://svn.domain.com/svn/project/one.rst।

आप निश्चित रूप से svninclude.py को पैकेज करना चाहते हैं और इसे अपने पायथन पथ में स्थापित करना चाहते हैं। यहां बताया गया है कि मैं यह परीक्षण करने के लिए किया था है:

1. जोड़ा गया 'svninclude'source/conf.py में extensions सूची में।
2. प्रोजेक्ट रूट में svninclude.py रखा गया।

फिर भाग गया:

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