Использование Sphinx для создания документации в нескольких форматах на CentOS 7

• Предпосылки
• Шаг 1: Обновите систему
• Шаг 2: Установите pip и Sphinx
• Шаг 3: Настройте базовую конфигурацию для вашей документации
• Шаг 4. Постройте иерархию для вашей документации
• Шаг 5: Создайте исходные файлы, указанные выше
• Шаг 6: Выведите HTML версию вашей документации

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 .

Шаг 6: Выведите HTML версию вашей документации

Как только вы закончите составление документации, вы можете вывести свою работу HTML format , выполнив следующую команду:

make html

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

На этом мы завершаем наш урок.