Brak generowania indeksu modułu "modindex" podczas używania Sphinx

Question

Mam problemy z tworzeniem katalogu dokumentów (html) przy użyciu sphinx-build.

Próbowałem

sphinx-build -b html source build 

jak również

make html 

ale w obu przypadkach tylko html pliki search.html index.html i genindex.html są generowane. Brak pliku modindex.html.

W conf.py pliku ustawić

html_domain_indices = True 

więc powinienem mieć plik modindex.html. Co ja robię źle? Po utworzeniu plików html nie pojawia się komunikat o błędzie. Używam Sphinx 1.1.3 i Python 2.7 w Windows XP.

Answer 1

Krótka wersja

• prowadzony sphinx-apidoc -o . mymodule
• Odkomentuj i modyfikować conf.py. W tym przykładzie, sys.path.insert(0, os.path.abspath('mymodule'))
• re-run make html

Długa odpowiedź

mogę odtworzyć problem z tym modułem próbki:

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

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

Running sphinx-quickstart daje następujące drzewo:

$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. 

z domyślnie index.rst:

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

Contents: 

.. toctree:: 
    :maxdepth: 2 



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

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

Running make html w tym momencie nie wytwarza moc w _build/html/py-modindex.html. Jest tak, ponieważ sphinx potrzebuje plików .rst opisujących każdy moduł. Na szczęście jest to łatwe do wyprodukowania przy użyciu sphinx-apidoc -o . mymodule. To daje dwa nowe pliki, z których tylko mymodule.rst jest konieczne, aby naprawić problem modindex w pytaniu.

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

.. toctree:: 
    :maxdepth: 4 

    mymodule 

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

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

Uruchomienie make html w tym momencie nadal nie będzie działać. Ale odkomentowanie i zmiana linii zaczynającej się od sys.path.insert w conf.py rozwiązuje pewne problemy.

Kopalnia jest: sys.path.insert(0, os.path.abspath('mymodule'))

PS: aby uniknąć dodatkowego ostrzeżenia dodać modules do Contents: toctree w pliku index.rst.