sphinx-doc/sphinxcontrib-django

📚 sphinxcontrib-django: Tài liệu API Django chuẩn chỉnh với Sphinx

Extension Sphinx giúp tài liệu tự động cho ứng dụng Django rõ ràng, đầy đủ và chuyên nghiệp hơn.

sphinxcontrib-django là một extension cho Sphinx, công cụ sinh tài liệu Python. Dự án nâng cấp đầu ra của autodoc khi dùng với các lớp Django như model và form, giúp thông tin tài liệu chính xác và dễ đọc hơn. Phù hợp với dự án Django muốn có bản tài liệu API chuyên nghiệp.

✨ Điểm nổi bật

• Liệt kê trường model và form: Tự động liệt kê tất cả trường (fields) của model và form dưới dạng tham số lớp.
• Cải thiện hiển thị trường trường: Tối ưu cách trường model được trình bày trong tài liệu.
• Liên kết quan hệ: Tự động tạo liên kết tới lớp tham chiếu cho trường quan hệ và ngược quan hệ.
• Ẩn thông tin không cần thiết: Loại bỏ các thông tin thời gian chạy như declared_fieldsets, fieldsets, Meta.
• Ghi chú phương thức tự động sinh: Thêm mô tả cho các phương thức được Django tự động tạo.
• Sửa lỗi intersphinx Django: Đảm bảo liên kết tới tài liệu Django hoạt động đúng.
• Tùy chỉnh liên kết tài liệu Django/Sphinx: Cung cấp text role như :setting:, :templatetag:, :event:, :confval:.

💡 Vì sao đáng chú ý

Không giống cách dùng autodoc mặc định chỉ hiển thị cấu trúc lớp thô, sphinxcontrib-django hiểu biết sâu về Django và tinh chỉnh hiển thị để phản ánh chính xác cấu trúc model, form và mối quan hệ. Điều này giúp nhà phát triển dễ dàng tìm hiểu và sử dụng lại mã nguồn.

Dự án hỗ trợ cả Sphinx 9+ với cấu hình bổ sung autodoc_use_legacy_class_based. Ngoài ra, cho phép hiển thị tên bảng database và số lượng lựa chọn (choices) trong trường model linh hoạt.

#Django #Sphinx #APIDocumentation #Python #TiniX