Automatyczne generowanie dokumentacji dla wszystkich zawartości pakietu Python

Question

Próbuję automatycznie generować podstawową dokumentację dla mojej bazy kodów za pomocą Sphinx. Mam jednak trudności z instruktażem Sphinx do rekurencyjnego skanowania moich plików.

Mam Python codebase o strukturze folderów jak:

<workspace> 
    src 
     mypackage 
      __init__.py 
      subpackageA 
       __init__.py 
       submoduleA1 
       submoduleA2 
      subpackageB 
       __init__.py 
       submoduleB1 
       submoduleB2 

Pobiegłem sfinks-QuickStart w <workspace>, więc teraz moja konstrukcja wygląda następująco:

<workspace> 
    src 
     mypackage 
      __init__.py 
      subpackageA 
       __init__.py 
       submoduleA1 
       submoduleA2 
      subpackageB 
       __init__.py 
       submoduleB1 
       submoduleB2 
    index.rst 
    _build 
    _static 
    _templates 

Czytałem quickstart tutorial http://sphinx.pocoo.org/tutorial.html, i chociaż wciąż próbuję zrozumieć dokumenty, sposób w jaki jest napisany sprawia, że ​​jestem zaniepokojony, że Sphinx zakłada, że ​​zamierzam ręcznie tworzyć pliki dokumentacji dla każdego modułu/klasy/funkcji w mojej bazie kodów.

Zauważyłem jednak komunikat "automodule" i włączyłem autodoc podczas szybkiego startu, więc mam nadzieję, że większość dokumentacji może zostać wygenerowana automatycznie. Zmodyfikowałem plik conf.py, dodając mój folder src do sys.path, a następnie zmodyfikowałem plik index.rst, aby użyć automodułu. Teraz mój index.rst wygląda następująco:

Contents: 

.. toctree:: 
    :maxdepth: 2 

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

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

.. automodule:: alphabuyer 
    :members: 

Mam kilkadziesiąt klas i funkcji zdefiniowanych w podpakietach. Jednak, gdy biegnę:

sphinx-build -b html . ./_build 

zgłasza:

updating environment: 1 added, 0 changed, 0 removed 

I to wydaje się, że nie udało się zaimportować niczego w moim pakiecie. Wyświetlanie wygenerowanego pliku index.html nic nie pokazuje obok "Treści:". Strona Index pokazuje tylko "mypackage (moduł)", ale kliknięcie go pokazuje również, że nie ma żadnej zawartości.

W jaki sposób kierujesz Sphinx, aby rekurencyjnie analizował pakiet i automatycznie generuje dokumentację dla każdej klasy/metody/funkcji, z którą się spotyka, bez potrzeby ręcznego wymieniania każdej klasy osobiście?

Answer 1

Być może apigen.py może pomóc: https://github.com/nipy/nipy/tree/master/tools.

To narzędzie zostało opisane bardzo krótko tutaj: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.

---

Update: narzędzie sphinx-apidoc dodano Sfinksa version 1.1.

Answer 2

Możesz spróbować użyć sfinksa-apidoc.

$ sphinx-apidoc --help 
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_paths, ...] 

Look recursively in <module_path> for Python modules and packages and create 
one reST file with automodule directives per package in the <output_path>. 

Można mieszać sfinks-apidoc z sfinks-QuickStart w celu stworzenia całego projektu doc ​​takiego:

$ sphinx-apidoc -F -o docs project 

Ta rozmowa będzie generować pełny projekt z sfinks-QuickStart i spojrzeć rekurencyjnie w (projekt) dla modułów Pythona.

Mam nadzieję, że to pomoże!

Answer 3

Uwaga

Dla Sfinksa (faktycznie, interpreter Pythona, który wykonuje Sfinksa), aby znaleźć moduł, to musi być importable. Oznacza to, że moduł lub opakowanie musi być w jednym z katalogów na sys.path - dostosować sys.path w pliku konfiguracyjnym odpowiednio

Tak, przejdź do conf.py i dodać

import an_example_pypi_project.useful_1 
import an_example_pypi_project.useful_2 

teraz twój index.rst wygląda następująco:

.. toctree:: 
    :glob: 

    example 
    an_example_pypi_project/* 

i

make html