Không tạo chỉ mục mô đun "modindex" khi sử dụng Sphinx

Question

Tôi gặp sự cố khi tạo thư mục tài liệu (html) bằng cách sử dụng nhân sư xây dựng.

tôi đã cố gắng

sphinx-build -b html source build 

cũng như

make html 

nhưng trong cả hai trường hợp chỉ html-files search.html, index.html và genindex.html được tạo ra. Tệp modindex.html bị thiếu.

Trong tập tin conf.py tôi đặt

html_domain_indices = True 

vì vậy tôi cần có một tập tin modindex.html. Tôi đang làm gì sai? Tôi không nhận được thông báo lỗi sau khi xây dựng các tệp html. Tôi đang sử dụng Sphinx 1.1.3 và Python 2.7 trên Windows XP.

Answer 1

ngắn phiên bản

• chạy sphinx-apidoc -o . mymodule
• bỏ ghi chú và chỉnh sửa conf.py. Trong ví dụ này, sys.path.insert(0, os.path.abspath('mymodule'))
• tái chạy make html

Long trả lời

tôi có thể tạo lại vấn đề với module mẫu này:

$cat mymodule/mymodule.py 
def fn1(): 
    '''First function''' 
    pass 

def fn2(): 
    '''Second function''' 
    pass 

Chạy sphinx-quickstart sản xuất cây sau:

$tree 
. 
├── Makefile 
├── _build 
├── _static 
├── _templates 
├── conf.py 
├── index.rst 
├── mymodule 
   └── mymodule.py 

$cat index.rst 
.. sphinx example documentation master file, created by 
    sphinx-quickstart on Mon Mar 30 15:28:37 2015. 
    You can adapt this file completely to your liking, but it should at least 
    contain the root `toctree` directive. 

với mặc định index.rst:

Welcome to sphinx example's documentation! 
========================================== 

Contents: 

.. toctree:: 
    :maxdepth: 2 



Indices and tables 
================== 

* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search` 

Chạy make html vào thời điểm này sản xuất không có đầu ra trong _build/html/py-modindex.html. Điều này là do sphinx cần các tệp .rst mô tả mọi mô-đun. May mắn là nó dễ dàng để sản xuất bằng cách sử dụng sphinx-apidoc -o . mymodule. Điều này cung cấp hai tệp mới, trong đó chỉ mymodule.rst là cần thiết để khắc phục vấn đề về modindex trong câu hỏi.

$head *mod*rst 
==> modules.rst <== 
mymodule 
======== 

.. toctree:: 
    :maxdepth: 4 

    mymodule 

==> mymodule.rst <== 
mymodule module 
=============== 

.. automodule:: mymodule 
    :members: 
    :undoc-members: 
    :show-inheritance: 

Chạy make html vào thời điểm này vẫn không hoạt động. Nhưng bỏ ghi chú và thay đổi dòng bắt đầu bằng sys.path.insert trong conf.py sửa chữa mọi thứ.

Mine là: sys.path.insert(0, os.path.abspath('mymodule'))

PS: để tránh một cảnh báo thêm, thêm modules đến Contents: toctree trong file index.rst.