ใช้สฟิงซ์เพื่อสร้างเอกสารในหลายรูปแบบบน CentOS 7

• ข้อกำหนดเบื้องต้น
• ขั้นตอนที่ 1: อัปเดตระบบ
• ขั้นตอนที่ 2: ติดตั้ง pip และ Sphinx
• ขั้นตอนที่ 3: ตั้งค่าการกำหนดค่าพื้นฐานสำหรับเอกสารของคุณ
• ขั้นตอนที่ 4: สร้างลำดับชั้นสำหรับเอกสารของคุณ
• ขั้นตอนที่ 5: สร้างไฟล์ต้นฉบับที่ระบุไว้ข้างต้น
• ขั้นตอนที่ 6: ส่งออกเวอร์ชันเอกสาร HTML ของคุณ

สฟิงซ์เป็นเครื่องมือที่ใช้ Python ที่มีประโยชน์สำหรับช่างเทคนิคและนักเขียนที่ช่วยให้พวกเขาสร้างเอกสารที่สง่างามและใช้งานง่ายในรูปแบบต่างๆได้อย่างง่ายดาย ด้วยสฟิงซ์คุณเขียนเอกสารโดยใช้ reStructuredText - ภาษามาร์กอัปน้ำหนักเบา - สำหรับ starters จากนั้นคุณสามารถรับเอาต์พุตในหลายรูปแบบรวมถึง HTML, LaTeX, PDF, ePub และอื่น ๆ

ในบทช่วยสอนนี้เราจะกล่าวถึงกระบวนการติดตั้งและใช้งานSphinxบน CentOS 7 x64 เช่นบนแพลตฟอร์มของ Vult

ข้อกำหนดเบื้องต้น

• อินสแตนซ์ CentOS 7 x64
• sudo ผู้ใช้

ขั้นตอนที่ 1: อัปเดตระบบ

sudo yum update
sudo shutdown -r now

ขั้นตอนที่ 2: ติดตั้ง pip และ Sphinx

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

ขั้นตอนที่ 3: ตั้งค่าการกำหนดค่าพื้นฐานสำหรับเอกสารของคุณ

ก่อนที่จะเริ่มใช้งานSphinxคุณต้องระบุไดเรกทอรีต้นทางของคุณซึ่งSphinxจะเรียกใช้และบันทึกเอกสารทั้งหมดของคุณ เมื่อคุณสร้างไดเรกทอรีที่คุณต้องการใช้แล้วคุณสามารถเรียกใช้sphinx-quickstartซึ่งจะเริ่มต้นSphinxและสร้างการกำหนดค่าพื้นฐานที่จำเป็น

sphinx-quickstart คล้ายกับตัวช่วยสร้างการตั้งค่าซึ่งจะแจ้งให้คุณคำถามที่กำหนดลักษณะของโครงการ

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

ขั้นตอนที่ 4: สร้างลำดับชั้นสำหรับเอกสารของคุณ

ตามค่าเริ่มต้นsphinx-quickstartตัวช่วยสร้างจะสร้างหลายไดเรกทอรีและไฟล์

_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

ลองมาดูที่ไฟล์ต้นแบบindex.rstซึ่งมีลำดับชั้นของเอกสารของคุณ toctreeคือโต๊ะของต้นไม้เนื้อหาหรือ

เปิดด้วยโปรแกรมแก้ไขข้อความ:

vi index.rst

toctreeในขณะที่คุณตรวจสอบไฟล์ที่คุณจะสังเกตเห็นส่วนที่เรียกว่า หากคุณมีไฟล์ต้นฉบับอื่น ๆ ( *.rst) สำหรับเอกสารของคุณคุณจะต้องระบุไฟล์เหล่านั้นในtoctreeส่วน: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

มีความจำเป็นต่อ:

• เว้นแถวว่างไว้เหนืออินพุตของคุณ
• .rstอย่าต่อท้ายไฟล์ที่มาของคุณด้วย
• วางไฟล์ต้นฉบับของคุณตามลำดับ
• ใช้ชื่อไฟล์เดียวต่อแถว
• :maxdepth: 2เยื้องชื่อไฟล์ของคุณด้วย

เมื่อคุณแก้ไขเสร็จแล้วให้บันทึกไฟล์และออกจากโปรแกรมแก้ไขข้อความ

ESC
:!wq

ขั้นตอนที่ 5: สร้างไฟล์ต้นฉบับที่ระบุไว้ข้างต้น

ไฟล์ต้นฉบับจะต้องสร้างขึ้นด้วยชื่อที่ตรงกับที่ระบุไว้ก่อนหน้านี้index.rstมิฉะนั้นจะไม่รวมอยู่ในผลลัพธ์สุดท้าย

reStructuredText markup languageไฟล์ทั้งหมดที่มาจะต้องเข้ากันได้กับ สำหรับข้อมูลเพิ่มเติมโปรดด���ที่reStructuredText รองพื้น

ขั้นตอนที่ 6: ส่งออกเวอร์ชันเอกสาร HTML ของคุณ

เมื่อคุณเขียนเอกสารของคุณเสร็จแล้วคุณสามารถส่งออกงานของคุณHTML format โดยดำเนินการคำสั่งด้านล่าง:

make html

ผลลัพธ์จะถูกบันทึกไว้ในไดเรกทอรี./\_build/htmlซึ่งรวมทุกอย่างที่จำเป็นสำหรับการดูไฟล์ในการท่องเว็บ

นี่เป็นการสรุปบทเรียนของเรา