Saya suka Doxygen untuk membuat dokumentasi kode C atau PHP. Saya memiliki proyek Python yang akan datang dan saya pikir saya ingat bahwa Python tidak memiliki /* .. */komentar, dan juga memiliki fasilitas dokumentasi sendiri yang tampaknya merupakan cara pythonic untuk mendokumentasikan.
Karena saya sudah familiar dengan Doxygen, bagaimana saya bisa menggunakannya untuk menghasilkan dokumentasi Python saya? Apakah ada hal khusus yang perlu saya waspadai?
Jawaban:
Ini didokumentasikan di situs web doxygen , tetapi untuk meringkasnya di sini:
Anda dapat menggunakan doxygen untuk mendokumentasikan kode Python Anda. Anda dapat menggunakan sintaks string dokumentasi Python:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
Dalam hal ini, komentar akan diekstraksi oleh doxygen, tetapi Anda tidak akan dapat menggunakan perintah doxygen khusus apa pun .
Atau Anda dapat (mirip dengan bahasa C-style di bawah doxygen) menggandakan penanda komentar ( #) di baris pertama sebelum anggota:
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
Jika demikian, Anda dapat menggunakan perintah doxygen khusus. Tidak ada mode keluaran Python tertentu, tetapi Anda tampaknya dapat meningkatkan hasil dengan mengatur OPTMIZE_OUTPUT_JAVAke YES.
Sejujurnya, saya sedikit terkejut dengan perbedaannya - sepertinya sekali doxygen dapat mendeteksi komentar di ## blok atau blok "" ", sebagian besar pekerjaan akan selesai dan Anda akan dapat menggunakan perintah khusus di apa pun kasusnya. Mungkin mereka mengharapkan orang yang menggunakan "" "untuk mematuhi lebih banyak praktik dokumentasi Pythonic dan itu akan mengganggu perintah doxygen khusus?
The doxypy filter input memungkinkan Anda untuk menggunakan hampir semua tag format Doxygen di Python format yang docstring standar. Saya menggunakannya untuk mendokumentasikan kerangka aplikasi game C ++ dan Python campuran yang besar, dan itu berfungsi dengan baik.
Pada akhirnya, Anda hanya memiliki dua pilihan:
Anda membuat konten Anda menggunakan Doxygen, atau Anda membuat konten menggunakan Sphinx *.
Doxygen : Ini bukan alat pilihan untuk sebagian besar proyek Python. Tetapi jika Anda harus berurusan dengan proyek terkait lainnya yang ditulis dalam C atau C ++, itu mungkin masuk akal. Untuk ini, Anda dapat meningkatkan integrasi antara Doxygen dan Python menggunakan doxypypy .
Sphinx : Alat defacto untuk mendokumentasikan proyek Python. Anda memiliki tiga opsi di sini: manual, semi-otomatis (generasi rintisan) dan otomatis sepenuhnya (seperti Doxygen).
autosummary_generatekonfigurasi. Anda perlu menyiapkan halaman dengan autosummaries, lalu mengedit halaman secara manual. Anda memiliki opsi, tetapi pengalaman saya dengan pendekatan ini adalah bahwa itu membutuhkan terlalu banyak konfigurasi, dan pada akhirnya bahkan setelah membuat templat baru, saya menemukan bug dan ketidakmungkinan untuk menentukan dengan tepat apa yang diekspos sebagai API publik dan apa yang tidak. Pendapat saya adalah alat ini bagus untuk pembuatan rintisan yang memerlukan pengeditan manual, dan tidak lebih. Seperti jalan pintas untuk berakhir secara manual.Ada opsi lain yang perlu diperhatikan:
__all__variabel explicite.
Sphinx terutama merupakan alat untuk memformat dokumen yang ditulis secara independen dari kode sumber, seperti yang saya pahami.
Untuk membuat dokumen API dari docstrings Python, alat terkemuka adalah pdoc dan pydoctor . Berikut dokumen API yang dihasilkan pydoctor untuk Twisted dan Bazaar .
Tentu saja, jika Anda hanya ingin melihat-lihat docstrings saat Anda mengerjakan sesuatu, ada alat baris perintah " pydoc " dan juga help()fungsi yang tersedia di interpreter interaktif.
Alat dokumentasi lain yang sangat bagus adalah sphinx . Ini akan digunakan untuk dokumentasi python 2.6 yang akan datang dan digunakan oleh django dan banyak proyek python lainnya.
Dari situs web sphinx: