Gunakan Sphinx Untuk Membuat Dokumentasi Dalam Pelbagai Format Di CentOS 7

• Prasyarat
• Langkah 1: Kemas kini sistem
• Langkah 2: Pasang pip dan Sphinx
• Langkah 3: Siapkan konfigurasi asas untuk dokumentasi anda
• Langkah 4: Bina hierarki untuk dokumentasi anda
• Langkah 5: Buat fail sumber yang dinyatakan di atas
• Langkah 6: Keluarkan versi HTML dari dokumentasi anda

Sphinx adalah alat berasaskan Python yang berguna untuk juruteknik dan penulis yang membolehkan mereka membuat dokumentasi yang elegan dan berfungsi sepenuhnya dalam pelbagai format. Dengan Sphinx, anda menulis dokumen menggunakan reStructuredText - bahasa penanda ringan - untuk permulaan, maka anda boleh mendapatkan output dalam pelbagai format, termasuk HTML, LaTeX, PDF, ePub, dan lain-lain.

Dalam tutorial ini, kita akan Sphinxmembahas proses pemasangan dan penggunaan pada instance CentOS 7 x64 di platform Vult.

Prasyarat

• Contoh CentOS 7 x64.
• Pengguna sudo .

Langkah 1: Kemas kini sistem

sudo yum update
sudo shutdown -r now

Langkah 2: Pasang 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: Siapkan konfigurasi asas untuk dokumentasi anda

Sebelum mula digunakan Sphinx, anda perlu menentukan direktori sumber anda yang Sphinxakan dijalankan dan menyimpan semua dokumentasi anda. Setelah anda membuat direktori yang ingin anda gunakan, anda kemudian boleh menjalankan sphinx-quickstartyang akan memulakan Sphinxdan membuat konfigurasi asas yang diperlukan.

sphinx-quickstart mirip dengan wizard persediaan yang akan menanyakan soalan yang menentukan aspek projek anda.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Langkah 4: Bina hierarki untuk dokumentasi anda

Secara lalai, sphinx-quickstartwizard akan membuat beberapa direktori dan fail.

_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 lihat fail induk index.rst, yang mengandungi hierarki dokumentasi anda; iaitu, pokok isi kandungan atau toctree.

Buka dengan editor teks:

vi index.rst

Semasa anda menyemak fail, anda akan melihat bahagian yang dipanggil toctree. Sekiranya anda mempunyai fail sumber lain ( *.rst) untuk dokumentasi anda, anda perlu menentukannya di toctreebahagian: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Adalah mustahak untuk:

• Tinggalkan baris kosong di atas input anda.
• Jangan akhiran fail sumber anda dengan .rst.
• Letakkan fail sumber anda mengikut urutan masing-masing.
• Gunakan hanya satu nama fail setiap baris.
• Masukkan nama fail anda dengan :maxdepth: 2.

Setelah selesai mengubah suai, simpan fail anda dan keluar dari editor teks.

ESC
:!wq

Langkah 5: Buat fail sumber yang dinyatakan di atas

Fail sumber mesti dibuat dengan nama yang sesuai dengan yang telah ditentukan sebelumnya index.rst, jika tidak, fail tersebut tidak akan dimasukkan dalam output akhir.

Semua fail sumber mesti serasi dengan reStructuredText markup language. Untuk maklumat lebih lanjut, sila rujuk reStructuredText Primer .

Langkah 6: Keluarkan versi HTML dari dokumentasi anda

Setelah selesai menyusun dokumentasi anda, anda dapat menghasilkan karya anda HTML format dengan melaksanakan perintah di bawah ini:

make html

Output akan disimpan dalam direktori ./\_build/htmlyang merangkumi semua yang diperlukan untuk melihat fail dalam penyemakan imbas web.

Ini menyimpulkan tutorial kami.