Tüm Python Paket İçeriği için Otomatik Olarak Belge Oluşturma

Question

Sphinx'i kullanarak kod tabanım için temel belgeleri otomatik olarak oluşturmaya çalışıyorum. Ancak, dosyalarımı tekrar taramak için Sfenks'e talimat vermekte zorlanıyorum.

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

Ben hızlı başlangıç ​​okudum: yani şimdi benim yapısı benziyor,

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

ben <workspace> içinde sfenks-quickstart ran

:

ben gibi bir klasör yapısı ile bir Python kod tabanına sahip öğretici http://sphinx.pocoo.org/tutorial.html, ve hala belgelerini anlamaya çalışıyorum rağmen, bana bu şekilde yaptığı gibi, Sphinx benim kod tabanımdaki her modül/sınıf/işlev için el ile belge dosyaları oluşturacağımı varsayar.

Ancak, "automodule" ifadesini fark ettim ve hızlı başlatma sırasında autodoc'u etkinleştirdim, bu yüzden belgelerin çoğunun otomatik olarak oluşturulabileceğini umuyorum. Src klasörümü sys.path dosyasına eklemek için conf.py'imi değiştirdim ve sonra automodule kullanmak için index.rst dizinimi değiştirdim. Ben alt paket tanımlanan sınıflar ve işlevlerin onlarca

Contents: 

.. toctree:: 
    :maxdepth: 2 

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

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

.. automodule:: alphabuyer 
    :members: 

: gibi Yani şimdi benim index.rst görünüyor. Oysa ben çalıştırdığınızda:

updating environment: 1 added, 0 changed, 0 removed 

Ve bu benim paketin içindeki herhangi bir şeye alınamadı gibi görünüyor:

sphinx-build -b html . ./_build 

o raporlar. Oluşturulan index.html'yi görüntülemek, "İçindekiler:" in yanında hiçbir şey göstermiyor. Dizin sayfasında sadece "mypackage (module)" gösterilir, ancak tıklatıldığında da içeriğinin olmadığı gösterilir.

Sphinx'i her paketi kendiniz listelemek zorunda kalmadan, bir paketi yinelemeli olarak ayrıştırmaya ve karşılaştığı her sınıf/yöntem/işlev için otomatik olarak belge oluşturmaya nasıl yönlendirirsiniz?

Answer 1

Belki apigen.py yardımcı olabilir: https://github.com/nipy/nipy/tree/master/tools.

Bu araç burada kısa bir şekilde anlatılmaktadır: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.

---

güncelle: sphinx-apidoc yardımcı Sphinx version 1.1 ilave edildi.

Answer 2

Sphinx-apidoc'u kullanmayı deneyebilirsiniz.

$ sphinx-apidoc -F -o docs project 

Bu çağrı sfenks-hızlı başlangıç ​​ile tam bir proje oluşturmak ve yinelemeli Look olacaktır:

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

Böyle tüm doc projesi oluşturmak amacıyla sfenks-hızlı başlangıç ​​ile sfenks-apidoc karıştırabilirsiniz Python modülleri için (proje).

Bu yardımcı olur umarız!

Answer 3

Not Sfenks (aslında Sfenks yürütür Python yorumlayıcısı) sizin modül bulmak için

, içe olmalıdır. Yani modül veya paket sys.path üzerindeki dizinleri birinde olması gerektiği anlamına gelir - buna göre

Yani, conf.py gidin yapılandırma dosyasında sys.path uyarlamak ve

import an_example_pypi_project.useful_1 
import an_example_pypi_project.useful_2 

Şimdi index.rst görünüyor eklemek gibi:

.. toctree:: 
    :glob: 

    example 
    an_example_pypi_project/* 

ve

make html