Làm cách nào để tránh cảnh báo "SEVERE: Duplicate ID" cho các mô-đun autodoc'd của tôi trong Sphinx?

Question

Tôi đang sử dụng RST/Sphinx tài liệu Python của tôi, tuy nhiên khi xây dựng nó ném cảnh báo như

...Code/doc/code.rst:3: SEVERE: Duplicate ID: "module-toast". 

My Python file nguồn được ghi nhận như sau:

#!/usr/bin/env python 
''' 
.. module:: toast 
    :synopsis: Processes the blobs produced by :mod:`bread`. 
''' 
# my inline-rST documented code... 

Và các tập tin RST sử dụng các autodoc cung cấp automodule chỉ thị để kéo tất cả các tài liệu ra và tài liệu tất cả các thành viên.

Toast 
-------------------------------- 

.. automodule:: toast 
    :members: 

Kết hợp ở trên dường như chỉ hoạt động tốt, nhưng lỗi dường như ngụ ý có cách thích hợp để thực hiện việc này. Nếu tôi loại bỏ các chỉ thị mô-đun từ phía trên của tập tin nguồn của tôi lỗi đi, nhưng sau đó tôi không thể thêm một tùy chọn tóm tắt trong nguồn đó được chọn bởi Nhân sư.

Answer 1

Tôi không chắc chắn, nhưng tôi tin rằng chỉ thị automodule sẽ tạo chỉ thị module trên chỉ riêng của nó. Sau đó, kể từ khi bạn đã có một quy định, có hai, và do đó bạn nhận được một thông báo ID trùng lặp.

Bạn có thể thử sử dụng chỉ thị currentmodule trong đánh dấu mô-đun của mình thay vì module. Có vẻ như là nên hoạt động, mặc dù tôi thừa nhận tôi chưa thực sự thử nó.

Answer 2

Có một cách để sử dụng cờ :noindex:.

.. automodule:: toast 
    :members: 
    :noindex: 

Sau đó, trong mã nguồn của bạn, bạn có thể sử dụng:

#!/usr/bin/env python 
''' 
.. module:: toast 
    :synopsis: Processes the blobs produced by :mod:`bread`. 
''' 

Sẽ có không có cảnh báo nghiêm trọng và tin nhắn trong tóm tắt sẽ xuất hiện trong chỉ số mô-đun.

Ở phía bên kia :noindex: sẽ ẩn mô-đun khỏi chỉ mục nếu mô-đun không có .. module:: trong tệp nguồn của chúng.

Answer 3

:noindex: cho automodule:: được viết bởi simno giúp nhưng ngăn việc tạo liên kết perma và liên kết chéo (ví dụ: :func:) sẽ không hoạt động. Khi thêm :noindex: vào module:: mọi thứ hoạt động như mong đợi và bạn không phải sử dụng currentmodule.