Создание документации: различия между версиями
Строка 36: | Строка 36: | ||
=== Инструменты документатора === | === Инструменты документатора === | ||
git, rpm-build-docs | git, rpm-build-docs, alt-docs-genextras | ||
==== rpm-build-docs ==== | ==== rpm-build-docs ==== | ||
Строка 80: | Строка 80: | ||
_автоматически_ пересобирать пакеты с документацией, _ничего_ не изменяя | _автоматически_ пересобирать пакеты с документацией, _ничего_ не изменяя | ||
в самих спеках (т. е. полностью без вмешательства человека). | в самих спеках (т. е. полностью без вмешательства человека). | ||
==== alt-docs-genextras ==== | |||
В ALT Linux предусмотрена стандартизованная процедура для | |||
включения вновь установленных выпусков документации | |||
в общую структуру электронной документации. | |||
Сценарий alt-docs-genextras, находящийся в данном пакете | |||
служит для автоматической генерации и обновления списка | |||
ссылок на установленные выпуски документации (пакеты docs-issue-*) | |||
на главной странице документации ALT Linux (пакет alt-docs-main). | |||
Этот сценарий вызывается после установки и удаления любого выпуска | |||
документации, для удобства есть rpm-макросы, находящиеся в пакете | |||
rpm-build-docs. | |||
Информация о пакете (файл docinfo) | |||
Текст ссылок, размещаемых на главной странице документации, | |||
автоматически генерируется на основании файла docinfo. | |||
По умолчанию такие файлы ищутся в подкаталогах | |||
/usr/share/doc/alt-docs/. | |||
Если файл docinfo содержит русскоязычный текст (что предполагается), | |||
он должен быть в кодировке koi8-r! | |||
В файле docinfo должна содержаться следующая информация: | |||
Title: Название документа. Название будет текстом гиперссылки | |||
на стартовую страницу документа (index.html). | |||
Abstract: Аннотация документа. Этот текст будет включён в оглавление | |||
и должен давать представление о тематике документа и о | |||
том, для кого он предназначен (опытный пользователь, | |||
новичок, любознательный и т. п.). Строгих требований | |||
к аннотации нет, но из неё читатель должен иметь возможность | |||
понять, что это за документ и нужно ли ему его читать. | |||
Допустимо и даже желательно, чтобы краткое описание пакета | |||
(поле %description -l ru_RU.KOI8-R в spec-файле пакета) | |||
совпадало с аннотацией. | |||
Section: Тематическая рубрика, в которую нужно поместить ссылку. | |||
В настоящее время пакет для помещения на главную страницу | |||
документации (alt-docs-main) здесь должно быть значение | |||
distrib. Другие значения игнорируются. | |||
Текущий формат файла docinfo таков: | |||
Начало примера | |||
Section: Название документа | |||
Abstract: Аннотация документа (достаточно информативная, | |||
поэтому длиной в несколько строк). | |||
Section: textbook | |||
Конец примера | |||
Обратите внимание: поля в файле docinfo должны быть разделены пустыми строками! | |||
==== Глоссарий терминов ==== | ==== Глоссарий терминов ==== | ||
== Пример создания модуля документации == | == Пример создания модуля документации == |
Версия от 10:31, 22 августа 2008
Описание процесса создания документации
Документация в репозитории/дистрибутивах
В рамках проекта создаётся документация, призванная помочь пользователям в освоении Linux.
Печатная документация
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux. Другой вид печатной документации -- отдельные книги, учебники и т.п.
Электронная документация
Электронная документация в виде rpm-пакетов присутствует в репозиториях. Как правило, именно на основе электронная документация создаются печатные версии.
Комплект электронной документации состоит из отдельных модулей, которые объединены выпуском.
Модуль представляет из себя самодостаточный текст, раскрывающий в той либо иной степени определённую тему. Например модуль может описывать процесс установки дополнительного ПО.
Выпуск не несёт в себе информативной части, а служит лишь для объединения модулей.
Аналогия: Файлы и Каталоги
Форматы документации
Электронная документация присутствует в установленной системе в виде html-файлов. Начальная страница каждого модуля содержит ссылку на паспорт модуля. Паспорт представляет из себя файл, содержащий различную мета-информацию: Автор, Версия, Тема, Краткое описание. Паспорт позволяет легче ориентироваться в большом количестве модулей.
Модули документации создаются разработчиком в одном из поддерживаемых форматов: html, docbook, m-k. Генерация html происходит в момент моздания пакета. Этот процесс автоматизирован и описан в разделе Цикл разработки.
Цикл разработки
git пакет репозиторий
Инструменты документатора
git, rpm-build-docs, alt-docs-genextras
rpm-build-docs
В пакете rpm-build-docs содержится несколько средств для автоматизации процесса превращения документа в пакет в Сизифе.
Общая задача -- сделать процесс подготовки пакетов максимально автоматизированным, сведя необходимое участие в нём человека к однократному созданию первоначального спека. А последующую пересборку пакета при всех обновлениях самого документа сделать по возможности автоматической.
В пакет входят следующие компоненты:
docs_genspec
Утилита, которая из указанного архива с документом (из Кучи) вынимает docinfo и на основе данных из него строит типичный спек-файл. Она умеет также обновлять уже имеющийся спек-файл (если он был некогда сгенерён этой же утилитой и не испорчен до неузнаваемости).
docsbuild
Скрипт, который запускает процесс сборки документации из исходного формата в html. В одном из аргументов ему передаётся название исходного формата. Дальше он смотрит по таблице, какая функция отвечает за сборку из этого формата в html и запускает эту функцию. Принципиально разрабатывался как расширяемый -- чтобы легко было добавлять новые функции для сборки html из других форматов.
Пользователь не должен вручную запускать docsbuild, он запускается при сборке пакета при помощи rpm-макроса, которому docs_genspec проставит нужные аргументы. У пользователя остаётся возможность добавить в спеке этому макросу любые дополнительные параметры для сборки (Естественно, их должна понимать сборочная функция для этого формата).
RPM-макросы
Нужны для того, чтобы не повторять стандартные операции в каждом спеке. Кроме того, последовательное использование макросов позволит при любых изменениях в этих стандартных операциях (т. е. в сборочной среде) _автоматически_ пересобирать пакеты с документацией, _ничего_ не изменяя в самих спеках (т. е. полностью без вмешательства человека).
alt-docs-genextras
В ALT Linux предусмотрена стандартизованная процедура для включения вновь установленных выпусков документации в общую структуру электронной документации.
Сценарий alt-docs-genextras, находящийся в данном пакете служит для автоматической генерации и обновления списка ссылок на установленные выпуски документации (пакеты docs-issue-*) на главной странице документации ALT Linux (пакет alt-docs-main).
Этот сценарий вызывается после установки и удаления любого выпуска документации, для удобства есть rpm-макросы, находящиеся в пакете rpm-build-docs.
Информация о пакете (файл docinfo)
Текст ссылок, размещаемых на главной странице документации, автоматически генерируется на основании файла docinfo. По умолчанию такие файлы ищутся в подкаталогах /usr/share/doc/alt-docs/.
Если файл docinfo содержит русскоязычный текст (что предполагается), он должен быть в кодировке koi8-r!
В файле docinfo должна содержаться следующая информация:
Title: Название документа. Название будет текстом гиперссылки на стартовую страницу документа (index.html).
Abstract: Аннотация документа. Этот текст будет включён в оглавление и должен давать представление о тематике документа и о том, для кого он предназначен (опытный пользователь, новичок, любознательный и т. п.). Строгих требований к аннотации нет, но из неё читатель должен иметь возможность понять, что это за документ и нужно ли ему его читать. Допустимо и даже желательно, чтобы краткое описание пакета (поле %description -l ru_RU.KOI8-R в spec-файле пакета) совпадало с аннотацией.
Section: Тематическая рубрика, в которую нужно поместить ссылку. В настоящее время пакет для помещения на главную страницу документации (alt-docs-main) здесь должно быть значение distrib. Другие значения игнорируются.
Текущий формат файла docinfo таков:
Начало примера Section: Название документа
Abstract: Аннотация документа (достаточно информативная, поэтому длиной в несколько строк).
Section: textbook Конец примера
Обратите внимание: поля в файле docinfo должны быть разделены пустыми строками!