استخدم أبو الهول لإنشاء وثائق بتنسيقات متعددة في CentOS 7

• المتطلبات الأساسية
• الخطوة 1: تحديث النظام
• الخطوة 2: تثبيت النقطة وأبو الهول
• الخطوة 3: إعداد التكوين الأساسي لوثائقك
• الخطوة 4: إنشاء التسلسل الهرمي للوثائق الخاصة بك
• الخطوة 5: إنشاء ملفات المصدر المحددة أعلاه
• الخطوة 6: إخراج نسخة HTML من وثائقك

Sphinx هي أداة مفيدة قائمة على Python للفنيين والكتاب تسمح لهم بسهولة بإنشاء وثائق أنيقة وكاملة الوظائف بتنسيقات مختلفة. مع Sphinx ، تكتب المستندات باستخدام reStructuredText - لغة ترميز خفيفة - للمبتدئين ، ثم يمكنك الحصول على الإخراج بتنسيقات متعددة ، بما في ذلك HTML و LaTeX و PDF و ePub وغيرها.

في هذا البرنامج التعليمي ، Sphinxسنغطي عملية التثبيت والاستخدام على مثيل CentOS 7 x64 على منصة Vult.

المتطلبات الأساسية

• مثيل CentOS 7 x64.
• A المستخدم سودو .

الخطوة 1: تحديث النظام

sudo yum update
sudo shutdown -r now

الخطوة 2: تثبيت النقطة وأبو الهول

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

الخطوة 6: إخراج نسخة HTML من وثائقك

بمجرد الانتهاء من تكوين الوثائق الخاصة بك ، يمكنك إخراج عملك من HTML format خلال تنفيذ الأمر أدناه:

make html

سيتم حفظ الإخراج في الدليل ./\_build/htmlالذي يتضمن كل ما هو ضروري لعرض الملف في تصفح الويب.

بهذا نختتم برنامجنا التعليمي.