epydoc के docstring स्वरूपण से sphinx docstring स्वरूपण में स्विच करने के लिए स्वचालित तरीका?

Question

मुझे एक प्रोजेक्ट मिला है जिसे मैंने epydoc का उपयोग करके दस्तावेज किया था। अब मैं स्फिंक्स पर स्विच करने की कोशिश कर रहा हूं। मैंने इनपुट, आउटपुट, अपवादों और पसंदों को समझाने के लिए बोल्डिंग, लिंकिंग और जैसे, और @param, @return, @raise आदि का उपयोग करके बी {}, एल {} इत्यादि का उपयोग करके epydocs के लिए मेरे सभी दस्तावेज़ों को स्वरूपित किया।

तो अब मैं स्फिंक्स पर स्विच कर रहा हूं, यह इन सभी सुविधाओं को खो देता है। क्या epydocs के लिए स्वरूपित डॉकस्ट्रिंग को sphinx के लिए स्वरूपित डॉकस्ट्रिंग में परिवर्तित करने के लिए एक स्वचालित तरीका है?

Answer 1

केविन हॉर्न के उत्तर पर विस्तार करने के लिए, autodoc-process-docstring ईवेंट द्वारा ट्रिगर किए गए ईवेंट हैंडलर में फोकस पर डॉकस्ट्रिंग का अनुवाद किया जा सकता है।

नीचे एक छोटा प्रदर्शन है (conf.py पर कोड जोड़कर इसे आजमाएं)। यह @ चरित्र को में : के साथ @ वर्ण को प्रतिस्थापित करता है, जिसका उपयोग संबंधित Sphinx fields में किया जाता है।

import re 

re_field = re.compile('@(param|type|rtype|return)') 

def fix_docstring(app, what, name, obj, options, lines): 
    for i in xrange(len(lines)): 
     lines[i] = re_field.sub(r':\1', lines[i]) 

def setup(app): 
    app.connect('autodoc-process-docstring', fix_docstring) 

Answer 2

सिद्धांत रूप में आप एक स्फिंक्स एक्सटेंशन लिख सकते हैं जो एक डॉकस्ट्रिंग पढ़ने पर हो सकता है जब भी घटना को निकाल दिया जाता है (source_read, हो सकता है?) और फ्लाई पर डॉकस्ट्रिंग का अनुवाद करें।

मैं सिद्धांत रूप में कहना है क्योंकि:

1. मैं एक बहुत लंबे समय के लिए ऐसी बात लिखने के लिए अर्थ किया गया है, लेकिन चारों ओर यह करने के लिए अभी तक पाने में कामयाब रहे नहीं किया है।
2. इस तरह की सामग्री का अनुवाद करना हमेशा की तुलना में कठिन होता है।

तुम भी शायद अभी सभी docstrings शायद ast मॉड्यूल या कुछ इसी तरह का उपयोग कर स्फिंक्स के बाहर एक समान अनुवादक के साथ अपने कोड में जगह की कोशिश कर सकते।

Answer 3

Pyment एक उपकरण है कि अजगर docstrings बदलने और लापता लोगों कंकाल बना सकते हैं। यह गूगल, Epydoc (जावाडोक शैली), Numpydoc, reStructuredText (बाकी है, स्फिंक्स डिफ़ॉल्ट) docstring स्वरूपों का प्रबंधन कर सकते हैं।

यह एक फ़ाइल या फ़ोल्डर स्वीकार करता है (उप-फ़ोल्डर भी खोज रहा है)। प्रत्येक फ़ाइल के लिए, यह प्रत्येक डॉकस्ट्रिंग प्रारूप को पहचान लेगा और इसे वांछित में परिवर्तित करेगा। अंत में, फ़ाइल पर लागू करने के लिए एक पैच उत्पन्न किया जाएगा।

अपनी परियोजना बदलने के लिए:

• Pyment स्थापित

प्रकार निम्नलिखित (एक virtualenv आप उपयोग कर सकते हैं):

$ git clone https://github.com/dadadel/pyment.git 
$ cd pyment 
$ python setup.py install 

• Epydoc से परिवर्तित करने के लिए स्फिंक्स

आप ऐसा करके स्फिंक्स प्रारूप (बाकी), जो कि डिफ़ॉल्ट उत्पादन प्रारूप है, अपनी परियोजना में बदल सकते हैं:

$ pyment /my/folder/project