از Sphinx برای ایجاد مستندات در قالب های مختلف در CentOS 7 استفاده کنید

• پیش نیازها
• مرحله 1: سیستم را به روز کنید
• مرحله 2: پیپ و ابوالهول را نصب کنید
• مرحله 3: پیکربندی اصلی را برای اسناد خود تنظیم کنید
• مرحله 4: سلسله مراتب را برای مستندات خود ایجاد کنید
• مرحله 5: پرونده های منبع مشخص شده در بالا ایجاد کنید
• مرحله ششم: از نسخه HTML اسناد خود استفاده کنید

Sphinx ابزاری مفید مبتنی بر پایتون برای تکنسین ها و نویسندگان است که به آنها اجازه می دهد تا به راحتی مستندات زیبا و کاملاً کاربردی را در قالب های مختلف ایجاد کنند. با Sphinx ، اسناد را با استفاده از reStructuredText - یک زبان نشانه گذاری سبک - برای مبتدیان می نویسید ، می توانید خروجی را در قالب های مختلفی از جمله HTML ، LaTeX ، PDF ، ePub و سایر موارد دریافت کنید.

در این آموزش ، روند نصب و استفاده از نمونه Sphinxای از CentOS 7 x64 را روی سکوی Vult پوشش خواهیم داد.

پیش نیازها

• به عنوان مثال CentOS 7 x64.
• کاربران از sudo .

مرحله 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 مراجعه کنید .

مرحله ششم: از نسخه HTML اسناد خود استفاده کنید

پس از اتمام تهیه مستندات ، می توانید HTML format با اجرای دستور زیر کارهای خود را انجام دهید:

make html

خروجی در دایرکتوری ذخیره می شود ./\_build/htmlکه شامل همه موارد لازم برای مشاهده پرونده در یک مرور وب است.

این نتیجه گیری آموزش ما است.