स्फिंक्स डिफ़ॉल्ट रूप से __in __ (स्व) के लिए डॉक्स उत्पन्न नहीं करता है। मैंने निम्नलिखित कोशिश की है:
.. automodule:: mymodule
:members:तथा
..autoclass:: MyClass
:members:Conf.py में, निम्नलिखित को सेट करना केवल __init __ को जोड़ता है (स्व) वर्ग docstring के लिए docstring ( Sphinx autodoc दस्तावेज़ीकरण इस बात से सहमत है कि यह अपेक्षित व्यवहार है, लेकिन इस समस्या के बारे में कुछ भी उल्लेख नहीं करता है जिसे मैं हल करने का प्रयास कर रहा हूं):
autoclass_content = 'both'जवाबों:
यहाँ तीन विकल्प दिए गए हैं:
यह सुनिश्चित करने के लिए कि __init__()हमेशा प्रलेखित है, आप autodoc-skip-memberconf.py में उपयोग कर सकते हैं । ऐशे ही:
def skip(app, what, name, obj, would_skip, options):
if name == "__init__":
return False
return would_skip
def setup(app):
app.connect("autodoc-skip-member", skip)यह स्पष्ट रूप __init__से छोड़ दिया नहीं जाना परिभाषित करता है (जो यह डिफ़ॉल्ट रूप से है)। यह कॉन्फ़िगरेशन एक बार निर्दिष्ट किया गया है, और इसे .rst स्रोत में हर वर्ग के लिए किसी भी अतिरिक्त मार्कअप की आवश्यकता नहीं है।
special-membersविकल्प था स्फिंक्स 1.1 में जोड़ा । यह "विशेष" सदस्य बनाता है (जैसे नाम वाले __special__) ऑटोडोक द्वारा दस्तावेज किए जाते हैं।
स्फिंक्स 1.2 के बाद से, यह विकल्प तर्क लेता है जो इसे पहले की तुलना में अधिक उपयोगी बनाता है।
उपयोग करें automethod:
.. autoclass:: MyClass
:members:
.. automethod:: __init__इसे हर वर्ग के लिए जोड़ा जाना चाहिए ( automoduleइस उत्तर के पहले संशोधन के लिए एक टिप्पणी में बताया गया है, जिसका उपयोग नहीं किया जा सकता है )।
special-membersका उपयोग करके ठीक काम करता है automodule। :special-members: __init__केवल दस्तावेज़ के लिए उपयोग करें __init__।
तुम पास थे। आप autoclass_contentअपनी conf.pyफ़ाइल में विकल्प का उपयोग कर सकते हैं :
autoclass_content = 'both'autoclass_content = 'both'विकल्प है, जो दस्तावेज़ किया init विधि है, लेकिन यह autosummary दो बार दिखाई दिया।
पिछले वर्षों में मैंने autodoc-skip-memberविभिन्न असंबंधित पाइथन परियोजनाओं के लिए कॉलबैक के कई प्रकार लिखे हैं क्योंकि मैं जैसी विधियाँ चाहता था __init__(), __enter__()और __exit__()अपने एपीआई प्रलेखन में दिखाने के लिए (आखिरकार, ये "विशेष विधियाँ" एपीआई का हिस्सा हैं और इससे बेहतर स्थान और क्या है? विशेष विधि के डॉकस्ट्रिंग के अंदर की तुलना में उन्हें दस्तावेज करें)।
हाल ही में मैंने सबसे अच्छा कार्यान्वयन लिया और इसे मेरी पायथन परियोजनाओं में से एक का हिस्सा बनाया ( यहाँ प्रलेखन )। कार्यान्वयन मूल रूप से इसके लिए आता है:
import types
def setup(app):
"""Enable Sphinx customizations."""
enable_special_methods(app)
def enable_special_methods(app):
"""
Enable documenting "special methods" using the autodoc_ extension.
:param app: The Sphinx application object.
This function connects the :func:`special_methods_callback()` function to
``autodoc-skip-member`` events.
.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
"""
app.connect('autodoc-skip-member', special_methods_callback)
def special_methods_callback(app, what, name, obj, skip, options):
"""
Enable documenting "special methods" using the autodoc_ extension.
Refer to :func:`enable_special_methods()` to enable the use of this
function (you probably don't want to call
:func:`special_methods_callback()` directly).
This function implements a callback for ``autodoc-skip-member`` events to
include documented "special methods" (method names with two leading and two
trailing underscores) in your documentation. The result is similar to the
use of the ``special-members`` flag with one big difference: Special
methods are included but other types of members are ignored. This means
that attributes like ``__weakref__`` will always be ignored (this was my
main annoyance with the ``special-members`` flag).
The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
if getattr(obj, '__doc__', None) and isinstance(obj, (types.FunctionType, types.MethodType)):
return False
else:
return skipहाँ, तर्क की तुलना में अधिक प्रलेखन है :-)। विकल्प autodoc-skip-memberके उपयोग पर इस तरह कॉलबैक को परिभाषित करने का लाभ special-members(मेरे लिए) यह है कि special-membersविकल्प उन संपत्तियों के प्रलेखन को भी सक्षम बनाता है जैसे __weakref__(सभी नई शैली की कक्षाओं, AFAIK पर उपलब्ध) जिसे मैं शोर मानता हूं और बिल्कुल भी उपयोगी नहीं है। कॉलबैक दृष्टिकोण इससे बचा जाता है (क्योंकि यह केवल कार्यों / विधियों पर काम करता है और अन्य विशेषताओं की उपेक्षा करता है)।
setup(app)स्फिंक्स द्वारा निष्पादित किए जाने के लिए विधि का नाम होना चाहिए ।
__init__विधि में एक गैर- रिक्त डॉकस्ट्रिंग है । क्या यह?
भले ही यह एक पुरानी पोस्ट है, लेकिन जो लोग इसे अभी तक देख रहे हैं, उनके लिए एक और समाधान भी है जो संस्करण 1.8 में पेश किया गया है। प्रलेखन के अनुसार , आप special-memberअपने लिए autodoc_default_options में कुंजी जोड़ सकते हैं conf.py।
उदाहरण:
autodoc_default_options = {
'members': True,
'member-order': 'bysource',
'special-members': '__init__',
'undoc-members': True,
'exclude-members': '__weakref__'
}यह एक वैरिएंट है जिसमें केवल __init__तर्क शामिल होने पर शामिल होता है:
import inspect
def skip_init_without_args(app, what, name, obj, would_skip, options):
if name == '__init__':
func = getattr(obj, '__init__')
spec = inspect.getfullargspec(func)
return not spec.args and not spec.varargs and not spec.varkw and not spec.kwonlyargs
return would_skip
def setup(app):
app.connect("autodoc-skip-member", skip_init_without_args)
"both" Both the class’ and the __init__ method’s docstring are concatenated and inserted.-> इसलिए, यह न केवल होना चाहिए__init__(self), बल्कि वर्ग डॉकस्ट्रिंग भी यदि आपके पास है। क्या आप एक परीक्षण मामला प्रदान कर सकते हैं क्योंकि यदि ऐसा है, तो यह बग जैसा लगता है, है ना?