Sphinx autodoc yeterince otomatik değil

Question

Python'da 5.000'den fazla projeyi belgelemek için Sphinx'i kullanmaya çalışıyorum. Yaklaşık 7 temel modüle sahiptir. Gibi bildiğim kadarıyla, AutoDoc kullanmak için Projemde her dosya için böyle kod yazmak gerekir: Birçok dosyaları olduğu için

.. automodule:: mods.set.tests 
    :members: 
    :show-inheritance: 

Bu yol çok can sıkıcı. Belgelendirilecek 'mods' paketini istediğimi belirtmek çok daha kolay olurdu. Sfenks daha sonra tekrar tekrar paketin içinden geçebilir ve her alt modül için bir sayfa hazırlayabilir.

Böyle bir özellik var mı? Eğer olmasaydı, bütün .stst dosyalarını yapmak için bir betik yazabilirdim, ama bu çok zaman alacaktı.

Answer 1

Yaptığım bu script numarasını kontrol edebilirsiniz. Sanırım size yardımcı olabilir.

Bu komut dosyası, python modülleri ve paketlerini arayan bir dizin ağacını ayrıştırır ve Sphinx ile kod belgeleri oluşturmak için ReST dosyalarını uygun şekilde oluşturur. Ayrıca bir modül indeksi oluşturur.

GÜNCELLEME

Artık bu komut dosyası apidoc olarak Sfenks 1.1 parçasıdır.

Answer 2

Her pakette, __init__.py dosya paketin her parçası için .. automodule:: package.module bileşenlerine sahip olabilir.

Sonra .. automodule:: package yapabilir ve çoğunlukla istediğinizi yapar.

Answer 3

Aradığınız şey Epydoc ve bu Sphinx extension.

Answer 4

ben Sfenks orijinal soru sorulmuştur anda autosummary uzantısı vardı mı bilmiyorum, ama şimdi onu sphinx-apidoc veya benzeri komut kullanmadan bu tür otomatik nesil kurmak oldukça mümkündür. Aşağıda projelerimden biri için çalışan ayarlar var.

1. conf.py dosyada autosummary uzantısını (yanı sıra autodoc) etkinleştirme ve True onun autosummary_generate seçeneğini ayarlayın. Özel *.rst şablonlarını kullanmıyorsanız bu yeterli olabilir. Aksi halde, listeyi dışlamak için şablonlar dizini ekleyin veya autosummary bunları giriş dosyaları olarak ele almaya çalışın (bu bir hata gibi görünüyor). senin index.rst dosyada TOK ağacında

   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary'] 
   autosummary_generate = True 
   templates_path = [ '_templates' ] 
   exclude_patterns = ['_build', '_templates'] 
   

2. kullanın autosummary::. Bu örnekte project.module1 ve project.module2 modülleri için belgeler otomatik olarak oluşturulacak ve _autosummary dizinine yerleştirilecektir. Varsayılan autosummary olarak

   PROJECT 
   ======= 
   
   .. toctree:: 
   
   .. autosummary:: 
       :toctree: _autosummary 
   
       project.module1 
       project.module2 
   

3. modülleri ve bunların fonksiyonları için sadece çok kısa özetleri üretecektir.Eğer (Jinja2 ile ayrıştırılır edileceği) _templates/autosummary/module.rst içine özel bir şablon dosyasını koyabilirsiniz bunu değiştirmek için: Sonuç olarak

   {{ fullname }} 
   {{ underline }} 
   
   .. automodule:: {{ fullname }} 
       :members: 
   

, sürüm kontrolü altında _autosummary dizini tutmak için gerek yoktur. Ayrıca, istediğiniz herhangi bir şeyi adlandırabilir ve kaynak ağacında herhangi bir yere yerleştirebilirsiniz (bunun yerine _build'un altına işlenmeyecektir).