स्फिंक्स

Question

में सशर्त टक्ट्री मैं दस्तावेज के कई संस्करणों को करना चाहता हूं, जो शामिल अनुभागों में भिन्न हैं। इसे प्राप्त करने के लिए मैं आमतौर पर only निर्देश या ifconfig एक्सटेंशन का उपयोग करता हूं। हालांकि, मैं toctree निर्देश के साथ संयोजन में से किसी का भी उपयोग नहीं कर सकता।

.. toctree:: 
    :maxdepth: 2 

    intro 
    strings 
    datatypes 
    numeric 
    .. only:: university 
     complex 

वहाँ ऐसा करने के लिए एक रास्ता है:

कुछ इस तरह क्या मैं मूल रूप से चाहते हैं?

Answer 1

जहाँ तक मुझे पता है कि आप जो चाहते हैं उसे करने का कोई तरीका नहीं है। मैं एक ही मुद्दे से जूझ रहा हूं, https://github.com/sphinx-doc/sphinx/issues/1717 देखें।

कारण यह है कि स्फिंक्स शुद्ध पाठ के रूप में एक टक्ट्री नोड में निहित सभी लाइनों को संसाधित करता है।

मैं दो विकल्प देखें:

1. आप अपने खुद के toctree निर्देश लिख सकते हैं;

2. आप एक विकल्प है कि अभिव्यक्ति शामिल

   .. toctree: 
       :condition: expression 
   
       file1 
   

मूल्यांकन किया जाना भी शामिल है toctree विस्तार कर सकते हैं और फिर आप doctree संकल्प घटना को अनुकूलित।

3. आप अपने टैग को परिभाषित कच्चे पाठ पर टेक्स्ट प्रतिस्थापन का उपयोग कर सकते हैं। आप स्रोत-पढ़ने की घटना के लिए एक ईवेंट हैंडलर को कार्यान्वित कर सकते हैं। उदाहरण $$condition$$ के लिए हो सकता है हालत का मूल्यांकन किया जाना है, जबकि $$$ ब्लॉक के अंत से, यानी

   .. toctree: 
   
       file1 
       $$mycondition$$ 
       file2 
       $$$ 
   

पर mycondition निर्भर करता है

, तो आपको निम्न ब्लॉक लाइनों निकाल सकते हैं।

संख्या 3 काफी सरल है, जबकि मुझे नंबर 2 सबसे सुरुचिपूर्ण है।

Answer 2

मेरा समाधान सशर्त सामग्री को एक अलग निर्देशिका 'इंटर्न' में रखना और टैग 'आंतरिक' का उपयोग करना है।

conf.py में मैं लाइनों

if tags.has('internal'): 
    exclude_patters = ['_build'] 
else: 
    exclude_patterns = ['_build', 'intern*'] 

अब प्रशिक्षु निर्देशिका में सामग्री को छोड़कर जोड़ा जब मैं कमांड लाइन मैं सभी पाने पर 'आंतरिक' झंडा गुजरती हैं, अन्यथा सब कुछ।

टैग आंतरिक केवल संयोजन के साथ उपयोग किया जा सकता है।

टीओसी में इंटर्न/somedoc के संदर्भ शामिल हैं और उन्हें आवश्यकतानुसार शामिल या छोड़ा गया है। मुझे लापता पृष्ठों के बारे में कई चेतावनियां मिलती हैं लेकिन उन्हें चुप किया जा सकता है।

Answer 3

एक अलग सरल समाधान अलग-अलग नामों के तहत दो अलग-अलग इंडेक्स फ़ाइलों को बनाए रखना है। आप conf.py में डिफॉल्ट रूप से किस इंडेक्स फ़ाइल का उपयोग करने के लिए निर्दिष्ट कर सकते हैं और कमांड लाइन पर -D master_doc=alternate-index का उपयोग करके एक विशेष निर्माण के लिए इसे ओवरराइड कर सकते हैं।

Answer 4

मेरा पिछला उत्तर विफल रहता है यदि आपके पास सामग्री की तालिका का पदानुक्रम है तो मैंने एक सरल toctree-filt निर्देश लिखा है जो प्रविष्टि के उपसर्ग के आधार पर प्रविष्टियों को फ़िल्टर करने में सक्षम है। उदाहरण के लिए, एक toctree-filt निर्देश की तरह

.. toctree-filt:: 
    :maxdepth: 1 

    user-manual 
    :internal:supervisor-api 
    :draft:new-feature 
    :erik:erik-maths 
    api 

दिया और ['draft','erik'] को अपवर्जन सूची सेट करने में कोई प्रभावी toctree ऐसा दिखता है जैसे

.. toctree-filt:: 
    :maxdepth: 1 

    user-manual 
    supervisor-api 
    api 

अपने conf.py में निम्नलिखित पंक्तियां जोड़ें में परिणाम होगा:

sys.path.append(os.path.abspath('../sphinx-ext/')) 
extensions = ['toctree_filter'] 
toc_filter_exclude = ['draft','erik'] 

अपनेके बगल में /sphinx_ext में निम्न कोड डालेंनिर्देशिका:

import re 
from sphinx.directives.other import TocTree 


def setup(app): 
    app.add_config_value('toc_filter_exclude', [], 'html') 
    app.add_directive('toctree-filt', TocTreeFilt) 
    return {'version': '1.0.0'} 

class TocTreeFilt(TocTree): 
    """ 
    Directive to notify Sphinx about the hierarchical structure of the docs, 
    and to include a table-of-contents like tree in the current document. This 
    version filters the entries based on a list of prefixes. We simply filter 
    the content of the directive and call the super's version of run. The 
    list of exclusions is stored in the **toc_filter_exclusion** list. Any 
    table of content entry prefixed by one of these strings will be excluded. 
    If `toc_filter_exclusion=['secret','draft']` then all toc entries of the 
    form `:secret:ultra-api` or `:draft:new-features` will be excuded from 
    the final table of contents. Entries without a prefix are always included. 
    """ 
    hasPat = re.compile('^\s*:(.+):(.+)$') 

    # Remove any entries in the content that we dont want and strip 
    # out any filter prefixes that we want but obviously don't want the 
    # prefix to mess up the file name. 
    def filter_entries(self, entries): 
     excl = self.state.document.settings.env.config.toc_filter_exclude 
     filtered = [] 
     for e in entries: 
      m = self.hasPat.match(e) 
      if m != None: 
       if not m.groups()[0] in excl: 
        filtered.append(m.groups()[1]) 
      else: 
       filtered.append(e) 
     return filtered 

    def run(self): 
     # Remove all TOC entries that should not be on display 
     self.content = self.filter_entries(self.content) 
     return super().run() 

अब बस toctree-filt के लिए अपने मौजूदा toctree निर्देशों को बदलने और आप प्रारंभ करने के लिए अच्छा कर रहे हैं। ध्यान दें कि स्फिंक्स त्रुटियों को पोस्ट करेगा क्योंकि यह उन फ़ाइलों को मिलेगा जो दस्तावेज़ में शामिल नहीं हैं। सुनिश्चित नहीं है कि इसे कैसे ठीक किया जाए।