Використовуйте Sphinx для створення документації в кількох форматах на CentOS 7

Sphinx — це корисний інструмент на основі Python для техніків і письменників, який дозволяє їм легко створювати елегантну, повністю функціональну документацію в різних форматах. За допомогою Sphinx ви пишете документи за допомогою reStructuredText — легкої мови розмітки — для початку, а потім ви можете отримати вихід у кількох форматах, включаючи 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 Primer .

Крок 6. Виведіть HTML-версію вашої документації

Після того, як ви завершите створення своєї документації, ви можете вивести свою роботу HTML format , виконавши наведену нижче команду:

make html

Вихідні дані будуть збережені в каталозі, ./\_build/htmlякий містить усе необхідне для перегляду файлу під час перегляду веб-сторінок.

На цьому наш підручник закінчується.