Создание документации: различия между версиями
Нет описания правки |
|||
| Строка 37: | Строка 37: | ||
git, rpm-build-docs ... | git, rpm-build-docs ... | ||
==== rpm-build-docs ==== | |||
В пакете rpm-build-docs содержится несколько средств для автоматизации | |||
процесса превращения документа в пакет в Сизифе. | |||
Общая задача -- сделать процесс подготовки пакетов максимально | |||
автоматизированным, сведя необходимое участие в нём человека | |||
к однократному созданию первоначального спека. А последующую | |||
пересборку пакета при всех обновлениях самого документа | |||
сделать по возможности автоматической. | |||
В пакет входят следующие компоненты: | |||
docs_genspec | |||
------------ | |||
Утилита, которая из указанного архива с документом (из Кучи) | |||
вынимает docinfo и на основе данных из него строит типичный спек-файл. | |||
Она умеет также обновлять уже имеющийся спек-файл (если он был | |||
некогда сгенерён этой же утилитой и не испорчен до неузнаваемости). | |||
docsbuild | |||
--------- | |||
Скрипт, который запускает процесс сборки документации из исходного | |||
формата в html. В одном из аргументов ему передаётся название исходного | |||
формата. Дальше он смотрит по таблице, какая функция отвечает за сборку | |||
из этого формата в html и запускает эту функцию. Принципиально | |||
разрабатывался как расширяемый -- чтобы легко было добавлять новые | |||
функции для сборки html из других форматов. | |||
Пользователь не должен вручную запускать docsbuild, он запускается при | |||
сборке пакета при помощи rpm-макроса, которому docs_genspec проставит нужные | |||
аргументы. У пользователя остаётся возможность добавить в спеке этому | |||
макросу любые дополнительные параметры для сборки (Естественно, их | |||
должна понимать сборочная функция для этого формата). | |||
RPM-макросы | |||
----------- | |||
Нужны для того, чтобы не повторять стандартные операции в каждом спеке. | |||
Кроме того, последовательное использование макросов позволит при любых | |||
изменениях в этих стандартных операциях (т. е. в сборочной среде) | |||
_автоматически_ пересобирать пакеты с документацией, _ничего_ не изменяя | |||
в самих спеках (т. е. полностью без вмешательства человека). | |||
==== Глоссарий терминов ==== | ==== Глоссарий терминов ==== | ||
== Пример создания модуля документации == | == Пример создания модуля документации == | ||
Версия от 10:28, 22 августа 2008
Описание процесса создания документации
Документация в репозитории/дистрибутивах
В рамках проекта создаётся документация, призванная помочь пользователям в освоении Linux.
Печатная документация
Печатная документация прилагается к дистрибутивам, выпускаемым ALT Linux. Другой вид печатной документации -- отдельные книги, учебники и т.п.
Электронная документация
Электронная документация в виде rpm-пакетов присутствует в репозиториях. Как правило, именно на основе электронная документация создаются печатные версии.
Комплект электронной документации состоит из отдельных модулей, которые объединены выпуском.
Модуль представляет из себя самодостаточный текст, раскрывающий в той либо иной степени определённую тему. Например модуль может описывать процесс установки дополнительного ПО.
Выпуск не несёт в себе информативной части, а служит лишь для объединения модулей.
Аналогия: Файлы и Каталоги
Форматы документации
Электронная документация присутствует в установленной системе в виде html-файлов. Начальная страница каждого модуля содержит ссылку на паспорт модуля. Паспорт представляет из себя файл, содержащий различную мета-информацию: Автор, Версия, Тема, Краткое описание. Паспорт позволяет легче ориентироваться в большом количестве модулей.
Модули документации создаются разработчиком в одном из поддерживаемых форматов: html, docbook, m-k. Генерация html происходит в момент моздания пакета. Этот процесс автоматизирован и описан в разделе Цикл разработки.
Цикл разработки
git пакет репозиторий
Инструменты документатора
git, rpm-build-docs ...
rpm-build-docs
В пакете rpm-build-docs содержится несколько средств для автоматизации процесса превращения документа в пакет в Сизифе.
Общая задача -- сделать процесс подготовки пакетов максимально автоматизированным, сведя необходимое участие в нём человека к однократному созданию первоначального спека. А последующую пересборку пакета при всех обновлениях самого документа сделать по возможности автоматической.
В пакет входят следующие компоненты:
docs_genspec
Утилита, которая из указанного архива с документом (из Кучи) вынимает docinfo и на основе данных из него строит типичный спек-файл. Она умеет также обновлять уже имеющийся спек-файл (если он был некогда сгенерён этой же утилитой и не испорчен до неузнаваемости).
docsbuild
Скрипт, который запускает процесс сборки документации из исходного формата в html. В одном из аргументов ему передаётся название исходного формата. Дальше он смотрит по таблице, какая функция отвечает за сборку из этого формата в html и запускает эту функцию. Принципиально разрабатывался как расширяемый -- чтобы легко было добавлять новые функции для сборки html из других форматов.
Пользователь не должен вручную запускать docsbuild, он запускается при сборке пакета при помощи rpm-макроса, которому docs_genspec проставит нужные аргументы. У пользователя остаётся возможность добавить в спеке этому макросу любые дополнительные параметры для сборки (Естественно, их должна понимать сборочная функция для этого формата).
RPM-макросы
Нужны для того, чтобы не повторять стандартные операции в каждом спеке. Кроме того, последовательное использование макросов позволит при любых изменениях в этих стандартных операциях (т. е. в сборочной среде) _автоматически_ пересобирать пакеты с документацией, _ничего_ не изменяя в самих спеках (т. е. полностью без вмешательства человека).