क्या उपज के लिए स्फिंक्स रीस्ट पायथन डॉकस्ट्रिंग फ़ील्ड है?

Question

मैं बाकी शैली docstrings उपयोग करने के लिए कोशिश कर रहा हूँ, यानि कि

def foo(bar): 
    """a method that takes a bar 

    :param bar: a Bar instance 
    :type bar: Bar 

वहाँ yields दस्तावेज़ के लिए एक मानक तरीका है? मैंने http://sphinx-doc.org/domains.html#info-field-lists देखा, ए-ला इस सवाल [Using javadoc for Python documentation], लेकिन कोई भाग्य नहीं है। मैं कुछ की तरह कल्पना कर रहा हूं,

:yields: transformed bars 
    :yield type: Baz 

धन्यवाद!

Answer 1

Google python style guide का कहना है:

ठीक। जनरेटर फ़ंक्शंस के लिए दस्तावेज़ स्ट्रिंग में "रिटर्न:" के बजाय "उपज:" का उपयोग करें।

उदाहरण here से लिया:

def example_generator(n): 
    """Generators have a ``Yields`` section instead of a ``Returns`` section. 

    Args: 
     n (int): The upper limit of the range to generate, from 0 to `n` - 1 

    Yields: 
     int: The next number in the range of 0 to `n` - 1 

    Examples: 
     Examples should be written in doctest format, and should illustrate how 
     to use the function. 

     >>> print [i for i in example_generator(4)] 
     [0, 1, 2, 3] 

    """ 
    for i in range(n): 
     yield i 

ध्यान दें कि यह एक आधिकारिक अजगर कोडन शैली गाइड नहीं है।

आप conf.py में extensions की सूची में जोड़कर Yields आप sphinxcontrib-napoleon विस्तार का उपयोग करने की आवश्यकता है उपयोग करने के लिए जा रहे हैं:

:

extensions = ['...', ..., 'sphinxcontrib.napoleon'] 

sphinxcontrib-napoleon docstring preprocessing कदम पर Yields कीवर्ड among others पहचान

नेपोलियन एक स्फिंक्स एक्सटेंशन है जो स्फिंक्स को NumPy और Google स्टाइल दस्तावेज़ दोनों को पार्स करने में सक्षम बनाता है तार - खान अकादमी द्वारा अनुशंसित शैली।

नेपोलियन एक पूर्व प्रोसेसर कि NumPy और गूगल शैली पार्स docstrings और उन्हें धर्मान्तरित से पहले स्फिंक्स उन्हें पार्स करने के लिए प्रयास करता है reStructuredText है। यह एक मध्यवर्ती चरण में होता है जबकि स्फिंक्स प्रलेखन संसाधित कर रहा है, इसलिए यह आपकी वास्तविक स्रोत कोड फ़ाइलों में डॉकस्ट्रिंग को संशोधित नहीं करता है।

---

व्यक्तिगत रूप से, मुझे लगता है कि के बाद से एक generator मूल रूप से एक function की एक विशेष मामला है Returns: का उपयोग कर काफी ठीक है।

Answer 2

मैंने दूसरे उत्तर की समीक्षा की है और यह मेरी राय में सवाल का जवाब नहीं देता है।

जनरेटर को दस्तावेज करने का तरीका, हालांकि सबसे अच्छा नहीं है, बाकी दस्तावेज़ों में :return का उपयोग करके है। नोटिस देने के लिए विवरण का प्रयोग करें कि यह जनरेटर है।

Google/Numpy शैली दस्तावेज़ों से पैदावार उपज को लौटने के लिए रूपांतरित करते हैं।

https://bitbucket.org/RobRuana/sphinx-contrib/src/a06ae33f1c70322c271a97133169d96a5ce1a6c2/napoleon/sphinxcontrib/napoleon/docstring.py?at=default&fileviewer=file-view-default#docstring.py-678:680

Answer 3

इटरेटर []

अजगर 3 टिप्पणी के रूप में कम से प्रलेखित इस के लिए एक मानकीकृत Iterator[] वाक्य रचना की पेशकश: https://docs.python.org/3/library/typing.html#typing.Generator

अजगर 3 से पहले, मैं सुझाव है कि आप इस वाक्य विन्यास का उपयोग करने के लिए बाद में बंदरगाह करना आसान है:

from typing import List 
def f(): 
    """ 
    :rtype: Iterator[:class:`SomeClass`] 
    """ 
    yield SomeClass() 

और अजगर 3 के बाद, वाक्य रचना के साथ https://pypi.python.org/pypi/sphinx-autodoc-annotation का उपयोग करें:

from typing import Iterator 
def f() -> Iterator[SomeClass]: 
    yield SomeClass()