Cara mendokumentasikan kode Python menggunakan Doxygen [closed]

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?

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

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

2. Sphinx : Alat defacto untuk mendokumentasikan proyek Python. Anda memiliki tiga opsi di sini: manual, semi-otomatis (generasi rintisan) dan otomatis sepenuhnya (seperti Doxygen).

   1. Untuk dokumentasi API manual, Anda memiliki autodoc Sphinx . Ini bagus untuk menulis panduan pengguna dengan elemen yang dihasilkan API yang disematkan.
   2. Untuk semi-otomatis Anda memiliki Sphinx autosummary . Anda dapat mengatur sistem build Anda untuk memanggil sphinx-autogen atau mengatur Sphinx Anda dengan 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.
   3. Sepenuhnya otomatis. Ini telah dikritik berkali-kali dan untuk waktu yang lama kami tidak memiliki generator Python API otomatis yang baik yang terintegrasi dengan Sphinx sampai AutoAPI datang, yang merupakan anak baru di blok tersebut. Sejauh ini, ini adalah yang terbaik untuk pembuatan API otomatis dengan Python (catatan: promosi diri tanpa malu).

Ada opsi lain yang perlu diperhatikan:

• Bernapas : ini dimulai sebagai ide yang sangat bagus, dan masuk akal ketika Anda bekerja dengan beberapa proyek terkait dalam bahasa lain yang menggunakan Doxygen. Idenya adalah menggunakan keluaran XML Doxygen dan memasukkannya ke Sphinx untuk menghasilkan API Anda. Jadi, Anda bisa menyimpan semua kebaikan Doxygen dan menyatukan sistem dokumentasi di Sphinx. Mengagumkan secara teori. Sekarang, dalam praktiknya, terakhir kali saya memeriksa proyek tersebut belum siap untuk produksi.
• pydoctor *: Sangat khusus. Menghasilkan keluarannya sendiri. Ini memiliki beberapa integrasi dasar dengan Sphinx, dan beberapa fitur bagus.

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:

• Format keluaran : HTML (termasuk Bantuan HTML Windows) dan LaTeX, untuk versi PDF yang dapat dicetak
• Referensi silang yang luas : markup semantik dan tautan otomatis untuk fungsi, kelas, istilah glosarium, dan informasi serupa
• Struktur hierarki : definisi mudah dari pohon dokumen, dengan tautan otomatis ke saudara kandung, orang tua dan anak
• Indeks otomatis : indeks umum serta indeks modul
• Penanganan kode : penyorotan otomatis menggunakan penyorot Pygments
• Ekstensi : pengujian otomatis cuplikan kode, penyertaan docstring dari modul Python, dan banyak lagi