Cara Mengatur Sphinx untuk Mendokumentasikan Kode Python Anda
Table of content:
Sphinx adalah salah satu alat paling populer untuk menghasilkan dokumentasi. Di seluruh komunitas Python, pengembang menggunakan perangkat lunak bebas dan sumber terbuka ini. Itu dapat mengekstrak teks langsung dari kode atau file markdown Anda dan kemudian menggunakannya untuk menghasilkan dokumentasi dalam berbagai format seperti teks biasa, HTML, PDF, dan EPUB.
Menyiapkan Sphinx
Sebelum Anda mengatur Sphinx, lihat apa fungsinya dan beberapa fitur utamanya.
Apa itu Sphinx dan Apa Fungsinya?
Seperti disebutkan, Sphinx adalah generator dokumentasi. Secara default, ia menggunakan bahasa markup reStructuredText (RST) tetapi melalui ekstensi pihak ketiga, ia juga dapat menggunakan Markdown, bahasa markup teks biasa yang populer. Itu kemudian mengonversi file RST atau penurunan harga ini ke HTML, PDF, halaman manual, atau format lain yang Anda inginkan.
Baca Juga:
Beberapa fitur yang termasuk Sphinx adalah:
- Kemampuan untuk menghasilkan dokumentasi dari kode.
- Kemampuan untuk merujuk silang halaman dokumen yang berbeda menggunakan tautan otomatis untuk fungsi, kelas, kutipan, dan istilah glosarium.
- Penyorotan sintaks untuk blok kode.
- Dukungan untuk tema yang dapat mengubah tampilan dan nuansa dokumen.
- Definisi mudah pohon dokumen melalui daftar isi.
- Kemampuan untuk berintegrasi dengan ekstensi pihak ketiga untuk menambahkan lebih banyak fungsionalitas ke dokumen seperti cuplikan kode pengujian.
Memasang Sphinx
Sebelum menginstal Sphinx, pastikan Anda telah menginstal Python 3 di lingkungan pengembangan Anda. Anda kemudian dapat menggunakan manajer paket pip untuk menginstal Sphinx dengan menjalankan perintah berikut di terminal Anda:
pip install sphinx
Ini akan mengunduh dan menginstal Sphinx dan dependensinya.
Setelah instalasi, jalankan perintah berikut pada prompt perintah.
sphinx-build --version
Jika semuanya bekerja dengan baik, Anda akan melihat nomor versi untuk paket Sphinx yang baru saja Anda instal.
Membuat Proyek Sphinx Baru
Setelah Anda menginstal Sphinx, arahkan ke direktori kerja Anda dan jalankan perintah sphinx-quickstart untuk membuat proyek Sphinx baru.
sphinx-quickstart
Perintah ini akan meminta Anda untuk menjawab serangkaian pertanyaan tentang cara mengonfigurasi proyek Sphinx Anda. Anda dapat menentukan nama proyek dan menggunakan opsi default untuk pertanyaan lainnya. Di masa mendatang, Anda mungkin ingin menyesuaikan tanggapan berdasarkan proyek Anda.
Jika Anda mencantumkan isi direktori Anda, Anda akan melihat bahwa perintah ini membuat beberapa file untuk Anda. conf.py berisi nilai-nilai konfigurasi dan index.rst berfungsi sebagai halaman selamat datang dari dokumentasi Anda. Direktori build akan menampung dokumentasi yang dihasilkan, dan Sphinx menggunakan Makefile (make.bat di Windows) untuk membuat dokumentasi.
Menulis Dokumentasi Menggunakan Sphinx
File index.rst di root direktori Anda adalah halaman beranda aplikasi Anda. Jadi, buka dengan editor teks seperti VS Code—atau editor kode gratis lainnya yang bagus—untuk mengeditnya.
Anda dapat mengubah index.rst sesuai keinginan Anda, tetapi satu hal yang paling tidak harus dimiliki adalah direktif root toctree (pohon daftar isi). Ini penting karena menghubungkan banyak file ke satu hierarki dokumen.
Untuk menambahkan dokumentasi ke file index.rst, Anda dapat menggunakan markup RST.
Sebagai contoh, perhatikan file index.rst untuk modul math_utils. File ini mungkin berisi ikhtisar singkat tentang tujuan modul dan daftar isi yang tertaut ke halaman lain dokumentasi.
Welcome to Math Utils
======================.. toctree::
:maxdepth: 2
Getting Started
---------------
To use this module, you'll need the following:
* Python installed.
* A text editor
Math Utils
----------
The `math-utils` module provides basic math functions like addition and
subtraction.
Anda dapat menambahkan lebih banyak file .rst sesuai kebutuhan. Misalnya, Anda dapat membuat panduan kontribusi dalam file bernama kontribusi. pertama yang berisi panduan kontribusi berikut.
Contributing Guide
==================We welcome contributions to our project! Here are some guidelines for
contributing:
- Fork the project on GitHub.
- Make your changes on a new branch.
- Write tests to ensure that your changes work correctly.
- Submit a pull request with your changes.
- Make any requested changes.
Thank you for contributing!
Anda kemudian dapat menautkan file ini dari index.rst dengan menambahkan bagian baru ke direktif toctree:
.. toctree::
:maxdepth: 2
:caption: Table of Contents
contributing
Ini membuat item baru bernama berkontribusi di daftar isi yang membawa pengguna ke halaman kontribusi saat diklik.
Setelah Anda menulis dokumentasi, langkah selanjutnya adalah membangunnya. Di sini, membuat dokumentasi berarti membuat halaman HTML, manual, atau PDF dari file RST.
Membangun Dokumentasi
Untuk membuat dokumentasi menggunakan Sphinx, Anda perlu menjalankan perintah make html di root folder tempat makefile berada.
make html
Anda akan melihat file HTML di folder build. Jika ada kesalahan selama pembuatan, Sphinx akan memberi tahu Anda di terminal.
Untuk melihat dokumentasi, buka file index.html di browser Anda:
Anda harus dapat menavigasi ke panduan berkontribusi dari daftar isi.
Menyesuaikan Dokumentasi
Saat ini, dokumentasi memiliki beberapa gaya dasar. Jika Anda ingin menyesuaikannya, mungkin dengan menambahkan warna merek Anda, atau bahkan menambahkan mode gelap, Anda dapat menginstal dan menggunakan yang lain tema bawaan atau buat tema khusus Anda sendiri.
Untuk mendemonstrasikan, coba ubah tema menjadi yang disebut alam:
- Buka file konfigurasi Sphinx conf.py di direktori proyek Sphinx Anda.
- Cari baris yang menentukan opsi html_theme dan ubah ke sifat
- Simpan file konfigurasi dan bangun kembali dokumentasi untuk melihat perubahan Anda.
Seperti inilah seharusnya tampilan beranda dokumentasi.
Jika Anda tidak ingin menggunakan tema bawaan, Anda selalu dapat menggunakan a tema Sphinx pihak ketiga alih-alih.
Mendokumentasikan Kode Anda Menggunakan Docstrings
Sphinx menghasilkan dokumentasi Python Anda dari teks yang Anda tulis di file RST. Meskipun ini cukup dalam beberapa kasus, Anda mungkin juga ingin menggunakan docstrings dalam kode Anda pada level modul.
Docstrings tinggal langsung di dalam file sumber proyek Anda. Mereka membiarkan Anda menjelaskan apa yang dilakukan kode, memberikan contoh, dan bahkan membuat pengujian untuk contoh tersebut. Setelah Anda menulis dokumen, Anda dapat membuat dokumentasi darinya menggunakan Sphinx.
Artikel Terkait
