Bir sınıfın __init __ (self) yöntemini belgelemek için Sphinx'in autodoc'u nasıl kullanılır?

Sphinx varsayılan olarak __init __ (self) için doküman oluşturmaz. Aşağıdakileri denedim:

.. automodule:: mymodule
    :members:

ve

..autoclass:: MyClass
    :members:

Conf.py'de, aşağıdakinin ayarlanması __init __ (self) docstring'i sınıf docstring'e ekler ( Sphinx autodoc dokümantasyonu bunun beklenen davranış olduğunu kabul ediyor gibi görünüyor, ancak çözmeye çalıştığım problemle ilgili hiçbir şey belirtmiyor):

autoclass_content = 'both'

İşte üç alternatif:

1. Bunun __init__()her zaman belgelendiğinden emin olmak için autodoc-skip-memberconf.py içinde kullanabilirsiniz . Bunun gibi:

   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)
   

   Bu, __init__atlanmamayı açıkça tanımlar (varsayılan olarak budur). Bu yapılandırma bir kez belirtilir ve .rst kaynağındaki her sınıf için herhangi bir ek işaretleme gerektirmez.

2. special-membersSeçenek oldu Sfenks 1.1 eklenmiştir . "Özel" üyelerin (gibi isimlere sahip olanlar __special__) autodoc tarafından belgelenmesini sağlar.

   Sphinx 1.2'den bu yana, bu seçenek argümanları alır ve bu da onu daha önce olduğundan daha kullanışlı hale getirir.

3. Kullanım automethod:

   .. autoclass:: MyClass     
      :members: 
   
      .. automethod:: __init__
   

   Bu, her sınıf için eklenmelidir automodule(bu cevabın ilk revizyonuna yapılan bir yorumda belirtildiği gibi kullanılamaz ).

Sen yakındın. Dosyanızdaki autoclass_contentseçeneği kullanabilirsiniz conf.py:

autoclass_content = 'both'

Son yıllarda ben birkaç çeşidini yazdım autodoc-skip-memberben yöntemler gibi istedi çünkü çeşitli ilgisiz Python projeler için geri aramaları __init__(), __enter__()ve __exit__()sonuçta, bu "özel yöntemler" API parçası ve ne daha iyi bir yer vardır (benim API belgelerinde göstermek onları özel yöntemin docstringinden daha belgeleyin).

Son zamanlarda en iyi uygulamayı aldım ve Python projelerimden birinin bir parçası yaptım ( işte belgeler ). Uygulama temelde şuna iner:

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

Evet, mantıktan daha fazla belge var :-). Bunun autodoc-skip-membergibi bir geri aramayı tanımlamanın special-membersseçeneğin kullanımına göre (benim için) avantajı , seçeneğin gürültü olduğunu düşündüğüm ve hiç kullanışlı olmadığını düşündüğüm (tüm yeni stil sınıflarında mevcut olan AFAIK) special-membersgibi özelliklerin dokümantasyonunu da etkinleştirmesidir __weakref__. Geri çağırma yaklaşımı bunu önler (çünkü yalnızca işlevler / yöntemler üzerinde çalışır ve diğer öznitelikleri göz ardı eder).

Bu daha eski bir gönderi olsa da, şu an itibariyle arayanlar için 1.8 sürümünde tanıtılan başka bir çözüm daha var. Belgelere göre special-member, autodoc_default_options içindeki anahtarı conf.py.

Misal:

autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Bu, yalnızca __init__argümanları varsa içeren bir değişkendir:

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)