Sphinx autodoc yeterince otomatik değil

Python'da 5.000'den fazla satırlık bir projeyi belgelemek için Sphinx'i kullanmaya çalışıyorum. Yaklaşık 7 temel modüle sahiptir. Bildiğim kadarıyla autodoc'u kullanmak için projemdeki her dosya için şu şekilde kod yazmam gerekiyor:

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

Bu çok sıkıcı çünkü birçok dosyam var. 'Mods' paketinin belgelenmesini istediğimi belirtebilseydim çok daha kolay olurdu. Sphinx daha sonra paketi tekrar tekrar gözden geçirebilir ve her alt modül için bir sayfa oluşturabilir.

Bunun gibi bir özellik var mı? Değilse, tüm .rst dosyalarını yapmak için bir komut dosyası yazabilirdim, ama bu çok zaman alırdı.

Yaptığım bu senaryoyu kontrol edebilirsiniz . Sana yardımcı olabileceğini düşünüyorum.

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

GÜNCELLEME

Bu script artık apidoc olarak Sphinx 1.1'in bir parçası .

autosummaryOrijinal soru sorulduğunda Sphinx'in bir uzantısı olup olmadığını bilmiyorum , ancak şimdilik bu türden otomatik üretimi sphinx-apidocveya benzer bir komut dosyası kullanmadan kurmak oldukça mümkün . Aşağıda projelerimden biri için çalışan ayarlar var.

1. Dosyadaki autosummaryuzantıyı (yanı sıra autodoc) etkinleştirin conf.pyve autosummary_generateseçeneğini olarak ayarlayın True. Özel *.rstşablonlar kullanmıyorsanız bu yeterli olabilir . Aksi takdirde, listeyi hariç tutmak için şablonlar dizininizi ekleyin veya autosummarybunları giriş dosyaları olarak işlemeye çalışın (bu bir hata gibi görünüyor).

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

2. Dosyanızdaki autosummary::TOC ağacında kullanın index.rst. Bu örnekte, modüller için dokümantasyon project.module1ve project.module2otomatik olarak oluşturulacak ve _autosummarydizine yerleştirilecektir .

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

3. Varsayılan olarak autosummary, modüller ve işlevleri için yalnızca çok kısa özetler üretecektir. Bunu değiştirmek için içine özel bir şablon dosyası koyabilirsiniz _templates/autosummary/module.rst( Jinja2 ile ayrıştırılacaktır ):

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

Sonuç olarak, _autosummarydizini sürüm kontrolü altında tutmaya gerek yoktur . Ayrıca, istediğiniz herhangi bir şeyi adlandırabilir ve kaynak ağacında herhangi bir yere yerleştirebilirsiniz (yine de aşağıya koymak _buildişe yaramayacaktır).

Sphinx sürüm 3.1'den (Haziran 2020), sphinx.ext.autosummary (nihayet!) Yineleme var.

Bu nedenle, artık otomatik paket algılamaları için modül adlarını sabit kodlamaya veya Sphinx AutoAPI veya Sphinx AutoPackageSummary gibi 3. taraf kitaplıklara güvenmeye gerek yok .

Belgelenecek Python 3.7 paketi örneği ( Github'daki koda bakın ve ReadTheDocs'taki sonuca bakın ):

mytoolbox
|-- mypackage
|   |-- __init__.py
|   |-- foo.py
|   |-- mysubpackage
|       |-- __init__.py
|       |-- bar.py
|-- doc
|   |-- source
|       |--index.rst
|       |--conf.py
|       |-- _templates
|           |-- custom-module-template.rst
|           |-- custom-class-template.rst

conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # Source code dir relative to this file

extensions = [
    'sphinx.ext.autodoc',  # Core library for html generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables
]
autosummary_generate = True  # Turn on sphinx.ext.autosummary

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

index.rst(yeni :recursive:seçeneğe dikkat edin ):

Welcome to My Toolbox
=====================

Some words.

.. autosummary::
   :toctree: _autosummary
   :template: custom-module-template.rst
   :recursive:

   mypackage

Bu, derinlemesine iç içe geçmiş olmasına rağmen paketteki her modülü otomatik olarak özetlemek için yeterlidir. Her modül için, o modüldeki her öznitelik, işlev, sınıf ve istisnayı özetler.

Garip bir şekilde, varsayılan sphinx.ext.autosummaryşablonlar her bir öznitelik, işlev, sınıf ve istisna için ayrı dokümantasyon sayfaları oluşturmaz ve bunlara özet tablolarından bağlantı verir. Şablonları aşağıda gösterildiği gibi genişletmek mümkündür, ancak bunun neden varsayılan davranış olmadığını anlayamıyorum - elbette çoğu insanın isteyeceği şey budur ..? Bunu bir özellik isteği olarak dile getirdim .

Varsayılan şablonları yerel olarak kopyalayıp onlara eklemem gerekiyordu:

• Kopya site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstiçinmytoolbox/doc/source/_templates/custom-module-template.rst
• Kopya site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstiçinmytoolbox/doc/source/_templates/custom-class-template.rst

İçine kanca custom-module-template.rstiçindedir index.rstkullanılarak yukarıda :template:seçeneği. (Varsayılan site paketleri şablonlarını kullanarak ne olduğunu görmek için bu satırı silin.)

custom-module-template.rst (sağda belirtilen ek satırlar):

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}
  
   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module Attributes

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

   .. autosummary::
      :toctree:                                          <-- add this line
      :template: custom-class-template.rst               <-- add this line
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
   :toctree:
   :template: custom-module-template.rst                 <-- add this line
   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

custom-class-template.rst (sağda belirtilen ek satırlar):

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:                                    <-- add at least this line
   :show-inheritance:                           <-- plus I want to show inheritance...
   :inherited-members:                          <-- ...and inherited members too

   {% block methods %}
   .. automethod:: __init__

   {% if methods %}
   .. rubric:: {{ _('Methods') }}

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Attributes') }}

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

Her pakette, __init__.pydosya .. automodule:: package.module, paketin her bölümü için bileşenlere sahip olabilir .

O zaman yapabilirsin .. automodule:: packageve çoğunlukla istediğini yapar.

Sphinx AutoAPI tam olarak bunu yapıyor.

Belki de aradığınız şey Epydoc ve bu Sphinx uzantısıdır .