Gunakan Sphinx Untuk Membuat Dokumentasi Dalam Berbagai Format Pada CentOS 7

• Prasyarat
• Langkah 1: Perbarui sistem
• Langkah 2: Instal pip dan Sphinx
• Langkah 3: Atur konfigurasi dasar untuk dokumentasi Anda
• Langkah 4: Bangun hierarki untuk dokumentasi Anda
• Langkah 5: Buat file sumber yang ditentukan di atas
• Langkah 6: Keluarkan versi HTML dari dokumentasi Anda

Sphinx adalah alat berbasis Python yang berguna untuk teknisi dan penulis yang memungkinkan mereka untuk dengan mudah membuat dokumentasi yang elegan dan berfungsi penuh dalam berbagai format. Dengan Sphinx, Anda menulis dokumen menggunakan reStructuredText - bahasa markup ringan - sebagai permulaan, maka Anda bisa mendapatkan output dalam berbagai format, termasuk HTML, LaTeX, PDF, ePub, dan lainnya.

Dalam tutorial ini, kita akan membahas proses menginstal dan menggunakan Sphinxinstance CentOS 7 x64 pada platform Vult.

Prasyarat

• Contoh CentOS 7 x64.
• Seorang pengguna sudo .

Langkah 1: Perbarui sistem

sudo yum update
sudo shutdown -r now

Langkah 2: Instal pip dan Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Langkah 3: Atur konfigurasi dasar untuk dokumentasi Anda

Sebelum mulai menggunakan Sphinx, Anda perlu menentukan direktori sumber Anda yang Sphinxakan menjalankan dan menyimpan semua dokumentasi Anda. Setelah Anda membuat direktori yang ingin Anda gunakan, Anda kemudian dapat menjalankan sphinx-quickstartyang akan menginisialisasi Sphinxdan membuat konfigurasi dasar yang diperlukan.

sphinx-quickstart mirip dengan wizard pengaturan yang akan meminta Anda dengan pertanyaan yang menentukan aspek proyek Anda.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Langkah 4: Bangun hierarki untuk dokumentasi Anda

Secara default, sphinx-quickstartwizard akan membuat beberapa direktori dan file.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

Mari kita lihat file master index.rst,, yang berisi hierarki dokumentasi Anda; yaitu, daftar isi pohon atau toctree.

Buka dengan editor teks:

vi index.rst

Saat Anda meninjau file, Anda akan melihat bagian yang disebut toctree. Jika Anda memiliki file sumber lain ( *.rst) untuk dokumentasi Anda, Anda harus menentukannya di toctreebagian: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Sangat penting untuk:

• Biarkan baris kosong di atas input Anda.
• Jangan sufiks file sumber Anda dengan .rst.
• Tempatkan file sumber Anda dalam urutannya masing-masing.
• Gunakan hanya satu nama file per baris.
• Indentasi nama file Anda dengan :maxdepth: 2.

Setelah Anda menyelesaikan modifikasi, simpan file Anda dan keluar dari editor teks.

ESC
:!wq

Langkah 5: Buat file sumber yang ditentukan di atas

File sumber harus dibuat dengan nama yang cocok dengan apa yang sebelumnya ditentukan index.rst, jika tidak mereka tidak akan dimasukkan dalam hasil akhir.

Semua file sumber harus kompatibel dengan reStructuredText markup language. Untuk informasi lebih lanjut, lihat Primer reStructuredText .

Langkah 6: Keluarkan versi HTML dari dokumentasi Anda

Setelah Anda selesai membuat dokumentasi, Anda dapat menampilkan pekerjaan Anda HTML format dengan menjalankan perintah di bawah ini:

make html

Keluaran akan disimpan dalam direktori ./\_build/htmlyang mencakup semua yang diperlukan untuk melihat file dalam penelusuran web.

Ini menyimpulkan tutorial kami.