Làm cách nào để ghi lại các lớp học mà không có tên mô-đun?

Question

Tôi đang cố gắng ghi lại gói python với sphinx và đã tạo thành công tệp html. Gói tôi đang tạo tài liệu bao gồm tập hợp các tệp *.py, hầu hết chứa một lớp với một vài tệp là mô-đun chính hãng có chức năng được xác định. Tôi không cần phải vạch trần sự thật là mỗi lớp học trong một mô-đun vì vậy tôi đã thêm các câu lệnh from phù hợp vào tệp __init__.py ví dụ:

from base import Base 

để người dùng có thể sử dụng lệnh import pkg và không sau đó phải chỉ rõ các mô-đun có chứa các lớp:

import pkg 
class MyBase(pkg.Base): # instead of pkg.base.Base ... 
... 

Vấn đề là nhân sư khăng khăng ghi lại lớp như pkg.base.Base. Tôi đã cố gắng đặt add_module_names = False trong conf.py. Tuy nhiên, kết quả này trong nhân sư cho thấy lớp đơn giản là Base thay vì pkg.Base. Ngoài ra, điều này cũng làm hỏng tài liệu của các cặp *.py tệp mà là mô-đun.

Làm cách nào để tạo sphinx hiển thị một lớp là pkg.Base? Và làm cách nào để đặt chỉ thị add_module_names có chọn lọc cho mỗi tệp *.py?

Answer 1

Câu trả lời ngắn: Bạn không nên. Chỉ cần trỏ nhân sư vào thư mục mã của bạn. Nhân sư tài liệu mã và cho thấy sự hirarchy mô-đun. Mô-đun cuối cùng sẽ được nhập hoàn toàn như thế nào trong tay của nhà phát triển, nhưng không phải là trách nhiệm của công cụ tài liệu.

Answer 2

Dưới đây là một cách để thực hiện những gì OP yêu cầu:

1. Thêm một danh sách __all__ trong pkg/__init__.py:

   from base import Base # Or use 'from base import *' 
   
   __all__ = ["Base"] 
   

2. Sử dụng .. automodule:: pkg trong file .rst.

Nhân sư sẽ xuất tài liệu có tên lớp được hiển thị là pkg.Base thay vì pkg.base.Base.