Sphinx tidak membuat dokumen untuk __init __ (self) secara default. Saya telah mencoba yang berikut ini:
.. automodule:: mymodule
:members:
dan
..autoclass:: MyClass
:members:
Di conf.py, pengaturan berikut hanya menambahkan docstring __init __ (self) ke kelas docstring ( dokumentasi autodoc Sphinx sepertinya setuju bahwa ini adalah perilaku yang diharapkan, tapi tidak menyebutkan apapun mengenai masalah yang saya coba selesaikan):
autoclass_content = 'both'
python
python-sphinx
autodoc
Jacob Marble
sumber
sumber
"both" Both the class’ and the __init__ method’s docstring are concatenated and inserted.
-> Oleh karena itu, seharusnya tidak hanya menjadi__init__(self)
, tetapi juga kelas docstring jika Anda memilikinya. Bisakah Anda memberikan test case karena jika demikian, rasanya seperti bug, bukan?Jawaban:
Berikut tiga alternatif:
Untuk memastikan bahwa
__init__()
selalu didokumentasikan, Anda dapat menggunakanautodoc-skip-member
di conf.py. Seperti ini:Ini secara eksplisit mendefinisikan
__init__
untuk tidak dilewati (yang secara default). Konfigurasi ini ditentukan sekali, dan tidak memerlukan markup tambahan untuk setiap kelas di sumber .rst.The
special-members
pilihan yang ditambahkan dalam Sphinx 1.1 . Itu membuat anggota "khusus" (mereka yang memiliki nama seperti__special__
) didokumentasikan oleh autodoc.Sejak Sphinx 1.2, opsi ini membutuhkan argumen yang membuatnya lebih berguna daripada sebelumnya.
Penggunaan
automethod
:Ini harus ditambahkan untuk setiap kelas (tidak dapat digunakan dengan
automodule
, seperti yang ditunjukkan dalam komentar pada revisi pertama jawaban ini).sumber
special-members
berfungsi dengan baik menggunakanautomodule
. Gunakan:special-members: __init__
untuk mendokumentasikan saja__init__
.Anda sudah dekat. Anda dapat menggunakan
autoclass_content
opsi diconf.py
file Anda :sumber
autoclass_content = 'both'
opsi, yang mendokumentasikan metode init , tetapi itu membuat autosummary muncul dua kali.Selama beberapa tahun terakhir saya telah menulis beberapa varian
autodoc-skip-member
callback untuk berbagai proyek Python yang tidak terkait karena saya ingin metode seperti__init__()
,__enter__()
dan__exit__()
muncul dalam dokumentasi API saya (bagaimanapun, "metode khusus" ini adalah bagian dari API dan tempat apa yang lebih baik untuk mendokumentasikannya daripada di dalam docstring metode khusus).Baru-baru ini saya mengambil implementasi terbaik dan menjadikannya bagian dari salah satu proyek Python saya ( berikut dokumentasinya ). Implementasinya pada dasarnya bermuara pada ini:
Ya, ada lebih banyak dokumentasi daripada logika :-). Keuntungan mendefinisikan
autodoc-skip-member
panggilan balik seperti ini dibandingkan penggunaanspecial-members
opsi (bagi saya) adalah bahwaspecial-members
opsi tersebut juga mengaktifkan dokumentasi properti seperti__weakref__
(tersedia di semua kelas gaya baru, AFAIK) yang menurut saya berisik dan tidak berguna sama sekali. Pendekatan callback menghindari ini (karena hanya bekerja pada fungsi / metode dan mengabaikan atribut lain).sumber
setup(app)
agar dapat dijalankan oleh Sphinx.__init__
metode Anda memiliki docstring tidak kosong. Melakukannya?Meskipun ini adalah posting yang lebih lama, tetapi bagi mereka yang melihatnya seperti sekarang, ada juga solusi lain yang diperkenalkan di versi 1.8. Menurut dokumentasi , Anda dapat menambahkan
special-member
kunci dalam autodoc_default_options keconf.py
.Contoh:
sumber
Ini adalah varian yang hanya disertakan
__init__
jika memiliki argumen:sumber