Autodoc i elementy dekoracyjne Python Sphinx

Question

Próbuję użyć Sphinx do udokumentowania mojej klasy Pythona. Mam więc korzystanie autodoktora:

.. autoclass:: Bus 
    :members: 

Chociaż poprawnie pobiera docstrings dla moich metod, te, które są urządzone:

@checkStale 
    def open(self): 
     """ 
     Some docs. 
     """ 
     # Code 

z @checkStale będąc

def checkStale(f): 
    @wraps(f) 
    def newf(self, *args, **kwargs): 
     if self._stale: 
      raise Exception 
     return f(self, *args, **kwargs) 
    return newf 

mieć nieprawidłową prototyp, na przykład open(*args, **kwargs).

Jak mogę to naprawić? Miałem wrażenie, że używanie tego rodzaju rzeczy będzie naprawiać za pomocą @wraps.

Answer 1

Aby rozwinąć na mój komentarz:

Have you tried using the decorator package and putting @decorator on checkStale? I had a similar issue using epydoc with a decorated function.

Ponieważ pytasz w swoim komentarzu, dekorator pakiet nie jest częścią biblioteki standardowej.

Można spaść z powrotem za pomocą kodu coś jak następuje (niesprawdzone):

try: 
    from decorator import decorator 
except ImportError: 
    # No decorator package available. Create a no-op "decorator". 
    def decorator(f): 
     return f 

Answer 2

UPDATE: może to być „niemożliwe”, aby zrobić czysto ponieważ sfinks używa kodu wynikowego funkcja do generowania swój podpis funkcji. Ale ponieważ używasz sfinksa, istnieje hacky obejście, które działa.

Jest hacky, ponieważ skutecznie wyłącza dekorator, gdy sfinks działa, ale działa, więc jest to praktyczne rozwiązanie.

Najpierw poszedłem na trasę budowy nowego obiektu types.CodeType, aby zastąpić element kodu obiektu func_code opakowania, który jest używany przez sfinks podczas generowania sygnatur.

Udało mi się zmusić do pęknięcia pytona, pokonując trasę lub próbując zamienić elementy obiektu kodu z pierwotnej funkcji, i jednocześnie odwołując się, było to zbyt skomplikowane.

Poniżej rozwiązanie, podczas gdy jest to hacky ciężki młot, jest również bardzo proste =)

Podejście jest następujący: podczas uruchamiania wewnątrz sfinksa, ustawić zmienną środowiskową, że dekorator można sprawdzić. wewnątrz dekoratora, gdy sfinks zostanie wykryty, nie rób w ogóle dekoracji, a zamiast tego zwróć oryginalną funkcję.

Wewnątrz sfinks conf.py:

import os 
os.environ['SPHINX_BUILD'] = '1' 

A potem tu jest modułem przykład z testu, który pokazuje, co to może wyglądać:

import functools 
import os 
import types 
import unittest 


SPHINX_BUILD = bool(os.environ.get('SPHINX_BUILD', '')) 


class StaleError(StandardError): 
    """Custom exception for staleness""" 
    pass 


def check_stale(f): 
    """Raise StaleError when the object has gone stale""" 

    if SPHINX_BUILD: 
     # sphinx hack: use the original function when sphinx is running so that the 
     # documentation ends up with the correct function signatures. 
     # See 'SPHINX_BUILD' in conf.py. 
     return f 

    @functools.wraps(f) 
    def wrapper(self, *args, **kwargs): 
     if self.stale: 
      raise StaleError('stale') 

     return f(self, *args, **kwargs) 
    return wrapper 


class Example(object): 

    def __init__(self): 
     self.stale = False 
     self.value = 0 

    @check_stale 
    def get(self): 
     """docstring""" 
     return self.value 

    @check_stale 
    def calculate(self, a, b, c): 
     """docstring""" 
     return self.value + a + b + c 


class TestCase(unittest.TestCase): 

    def test_example(self): 

     example = Example() 
     self.assertEqual(example.get(), 0) 

     example.value = 1 
     example.stale = True 
     self.assertRaises(StaleError, example.get) 

     example.stale = False 
     self.assertEqual(example.calculate(1, 1, 1), 4) 


if __name__ == '__main__': 
    unittest.main() 

Answer 3

Dodano w wersji 1.1 można zastąp teraz podpis metody, podając wartość niestandardową w pierwszym wierszu dokumentu.

http://sphinx-doc.org/ext/autodoc.html#confval-autodoc_docstring_signature

@checkStale 
def open(self): 
    """ 
    open() 
    Some docs. 
    """ 
    # Code 

Answer 4

Jeśli jesteś szczególnie nieugięty o nie dodawanie tutaj kolejną zależność jest to fragment kodu, który działa przy regularnym inspektora poprzez wstrzyknięcie do docstring. Jest dość hackey i niezbyt polecany, chyba że istnieją dobre powody, by nie dodawać kolejnego modułu, ale oto jest.

# inject the wrapped functions signature at the top of a docstring 
args, varargs, varkw, defaults = inspect.getargspec(method) 
defaults =() if defaults is None else defaults 
defaults = ["\"{}\"".format(a) if type(a) == str else a for a in defaults] 
l = ["{}={}".format(arg, defaults[(idx+1)*-1]) if len(defaults)-1 >= idx else arg for idx, arg in enumerate(reversed(list(args)))] 
if varargs: allargs.append('*' + varargs) 
if varkw: allargs.append('**' + varkw) 
doc = "{}({})\n{}".format(method.__name__, ', '.join(reversed(l)), method.__doc__) 
wrapper.__doc__ = doc 

Answer 5

Miałem ten sam problem z dekoratorem selera @task.

Można również naprawić w przypadku dodając prawidłowego podpisu funkcji do pliku rst, tak:

.. autoclass:: Bus 
    :members: 

    .. automethod:: open(self) 
    .. automethod:: some_other_method(self, param1, param2) 

Będzie on nadal dokumentować członków non-dekoratorów automatycznie.

Jest to wspomniane w dokumentacji sfinksa pod numerem http://sphinx-doc.org/ext/autodoc.html#directive-automodule - jest to przydatne, gdy podpis z metody jest ukryty przez dekoratora. "

W moim przypadku musiałem użyć autofunction określić podpis moich zadań selera w tasks.py modułu app django:

.. automodule:: django_app.tasks 
    :members: 
    :undoc-members: 
    :show-inheritance: 

    .. autofunction:: funct1(user_id) 
    .. autofunction:: func2(iterations)