Sphinx autodoc daje OSTRZEŻENIE: py: nie znaleziono celu odniesienia klasy: ostrzeżenie typu

Question

Mam kod, który używa metaclass w python. Ale kiedy sfinks AutoDoc prowadzony jest dające błąd:

WARNING: py:class reference target not found: type

Błąd jest występujących w linii auto generowane .rst plik:

.. automodule:: API.list.blockList 
    :members: # this is the line in error 
    :show-inheritance: 

I blocklist rozciąga API.list. lista, która ma \__metaclass__ ustawiona na mój metaclass.

Z tego, co mogę powiedzieć, że sfinks nie sądzi, że istnieje klasa typu wbudowanego. Próbowałem zaimportować typ wbudowany, aby sfinks zdał sobie sprawę z jego obecności, ale to nie zadziałało.

Po usunięciu przypisania metaclass z API.list.list i usunięciu metaclass z kodu, sfinks działa dobrze.

Answer 1

Jest to po prostu błąd w samych dokumentach Pythona - odniesienia do niektórych wbudowanych w Python (w tym type) nie powodują poprawnego działania (patrz na przykład https://bugs.python.org/issue11975).

Aby wyłączyć ostrzeżenie, można dodać opcję nitpick_ignore do konfiguracji Sphinx. Na przykład w ramach projektu Astropy mamy:

nitpick_ignore = [('py:class', 'type')] 

W rzeczywistości, istnieje wystarczająco dużo wyjątków, że wystarczy umieścić je wszystkie w oddzielnym pliku, który czytamy je z. Zobacz:

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/conf.py#L195

i dla pliku wyjątków sama:

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/nitpick-exceptions

Wiele wyjątków w powyższym pliku są specyficzne dla Astropy, ale inni rozwiązać niektóre połamane odniesień w Pythonie oraz w Numpy i może być ogólnie użyteczny.