Sphinx autodoc cho CẢNH BÁO: py: không tìm thấy mục tiêu tham chiếu lớp: cảnh báo kiểu

Question

Tôi có một số mã sử dụng một metaclass trong python. Nhưng khi autodoc Sphinx được chạy nó là đưa ra các lỗi:

WARNING: py:class reference target not found: type

Các lỗi đang xảy ra trong một dòng được tự động tạo tập tin .rst:

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

và danh sách chặn mở rộng API.list. danh sách có \__metaclass__ được đặt thành metaclass của tôi.

Từ những gì tôi có thể nói nhân sư không nghĩ rằng lớp loại nội trang tồn tại. Tôi đã cố gắng nhập khẩu các loại nội trang để làm cho nhân sư nhận ra nó có nhưng điều đó đã không làm việc.

Nếu tôi xóa bài tập metaclass khỏi API.list.list và xóa metaclass khỏi mã thì nhân sư hoạt động tốt.

Answer 1

Đây chỉ là lỗi trong tài liệu Python - tham chiếu đến một số trình xây dựng Python (bao gồm type) không giải quyết chính xác (xem ví dụ https://bugs.python.org/issue11975).

Để làm cho cảnh báo biến mất, bạn có thể thêm tùy chọn nitpick_ignore vào cấu hình Sphinx của mình. Ví dụ về dự án Astropy, chúng tôi có:

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

Thực tế, có đủ ngoại lệ mà chúng tôi đưa tất cả vào một tệp riêng biệt mà chúng tôi đọc chúng. Xem:

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

và cho các tập tin ngoại trừ bản thân:

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

Nhiều người trong số các trường hợp ngoại lệ trong file trên là đặc trưng cho Astropy, nhưng những người khác giải quyết một số tài liệu tham khảo tấm bằng Python và trong Numpy, và có thể hữu ích về mặt tổng quát.