http://www.aros.org AROS-Exec AROS-Exec Archives Power2People
kitty mascottop logo menu

Руководство по документированию AROS

Предупреждение

Этот документ не окончен! Вполне возможно, что многие части устарели, содержат некорректную информацию или полностью отсутствуют. Если вы хотите исправить их, пожалуйста сообщите нам.

Это руководство описывает систему документирования AROS. Оно предназначено как для тех, кто пишет документацию, так и для разработчиков, желающих описать или исправить саму систему. Руководство составлено из трёх частей: общего введения в систему, как использовать её для написания документации и наконец, технические замечания и спецификации. Не считая информации о пользовании самой системой, вторая глава также содержит общие рекомендации, которым надо следовать при написании документации к AROS.

Содержание

Введение

Документация жизненно важна для любого проекта, делая его пригодным к использованию. Обычно, в таких ограниченных в количестве разработчиков проектах, как наш, документация пишется в последнюю очередь или просто отсутствует. Также, большинство программистов не настолько хороши в написании документации, как в программировании, поэтому то, что уже написано обычно не очень удобочитаемо. Необходимо объединить усилия разработчиков и пользователей в документировании для достижения цели под названием "полностью документированная AROS". Так что, если вы знаете пользователей, которые могут нам помочь, зовите их! :)

Поправить: Написать подробнее?

Написание документации

Формат документации, которым мы пользуемся, называется reStructuredText (или ReST для краткости), разработанный проектом Docutils. ReST лёгок для чтения и записи, соответствует принципу WYSIWYG (что-ты-видишь-это-то-что-получишь), расширяем, синтаксис основан на разметке простого неформатированного текста.

Его можно назвать гибридом явного и неявного синтаксиса разметки, что делает его лёгким для изучения и весьма удобочитаемым, но при этом он остаётся мощным и расширяемым. Введение в reStructuredText содержит несколько хороших замечаний о целевом синтаксисе.

Так как основой является неформатированный текст, то его очень легко изучить, просто просматривая существующую документацию и руководствуясь здравым смыслом, но всё же рекомендуется прочитать хотя бы Пример использования reStructuredText перед началом работы над документацией к AROS.

Для получения более подробной информации о формате рекомендуются для прочтения следующие документы:

Архив документации

Для того, чтобы изменять или писать документацию вам надо получить ветку 'documentation' из дерева версий Subversion. Ветка с архивом документов содержит:

  • некоторые общие документы, например contact.en, links.en и т.д.
  • директорию 'db' с некоторой статистической информацией о проекте
  • директорию 'documentation', содержащую документацию для разработчиков и пользователей
  • директорию 'images' с изображением для контента страничек - баннеры, лого и т.п.
  • директорию 'introduction' с введением в проект, содержащимся в соответствующем пункте меню
  • директорию 'misc' с некоторыми вспомогательными файлами.
  • директорию 'news' с новостями, которые вы видите на начальной странице. Формат имен файлов новостей ГГГГММДДД.<суффикс>
  • директорию 'pictures' с фотографиями разработчиков и снимками экрана
  • директорию 'scripts' со скриптами используемыми для создания содержимого в HTML и другого WWW-контента
  • директорию 'targets' с дополнительными файлами для создания контента
  • ...

Примечание

Название 'documentation' имеет как ветка Subversion, так и вложенная в неё директория с документацией для разработчиков. Не путайте их.

Поддиректории

Вы можете создавать дополнительные директории в 'documentation/users' и 'documentation/developers'. Система сборки рекурсивно сканирует все поддиректории. В новых директориях рекомендуется создавать файл 'index.en'.

Интернационализация

Система сборки поддерживает интернационализацию для содержимого директории 'www'. Вы можете добавить к имени файла суффикс, указывающий на язык (например, commands.en). На данный момент поддерживаются английский (.en), немецкий (.de), финский (.fi), итальянский (.it), русский (.ru), шведский (.sv) и голландский (.nl) языки. Если вы хотите перевести документацию на большее количество языков, пожалуйста свяжитесь с нами через список рассылки.

Когда вы создаёте ссылку на документ вы можете пренебречь суффиксом и не добавлять его (например, `Commands <user/commands>`_), но если вы используете в переведённых документах директиву 'include', то вы должны добавлять суффикс.

Система сборки использует английскую версию, если недоступна переведённая страница.

Пример кода

Директория 'documentation/developers/samplecode' создана для примеров исходного программного кода. Содержимое скопировано сюда без изменений.

Изображения

Имена изображений и пути к ним жёстко задаются в скрите 'buildit.py' написанном на Python'е. Если вы хотите добавить изображение, то надо изменить скрипт соответствующим образом. Не стесняйтесь попросить об этом в списке рассылки для разработчиков, если вы хотите изменить скрипт.

Публикование изменений

Перед тем как фиксировать новые или изменённые документы вам следует создать локально копию HTML и WWW-контента. Следите за сообщениями об ошибках и исправляйте их. Проверьте результат с помощью браузера. Обычно изменения добавляются на http://aros.sourceforge.net/ спустя несколько часов после их передачи.

Технические замечания

Базы данных

Есть несколько маленьких баз данных, которые вы можете найти в директории db. Все они представляют из себя обычные текстовые файлы, но используют несколько слегка отличающихся форматов. Это по большей части исторический артефакт и возможно, следует профильтровать содержимое в будущем, но сейчас проще оставить всё как есть.

credits

Это список людей внёсших свой вклад в AROS. Система сборки в первую очередь создаёт файл 'credits.en'. Этот файл используется при сборке содержимого директорий WWW и HTML. Пожалуйста, помните, что при изменении файла 'credits' вам также надо изменить файл workbench/system/AboutAROS/db/credits в репозитории AROS.

quotes

Памятные цитаты знаменитостей мира AROS. Формат: цитата;автор. Система сборки копирует этот файл в директорию WWW.

mirrors

С тех пор как AROS пользуется хостингом на Sourceforge больше никаких зеркал нет. Этот файл игнорируется системой сборки.

tasks

База данных того, что надо сделать (TODO). Этот файл не поддерживается в течение длительного времени и не используется при создании директорий HTML и WWW.

Sizes

Файлы aros.size и contrib.size больше не используются и возможно будут удалены.

Building

Требования

Для сборки документации AROS "с нуля" вам потребуется следующее:

  • Python 2.2.1, интерпретатор языка программирования Python

Для сборки сайта дополнительно понадобится графическая библиотека:

В MacOS X интерпретатор Python предустановлен по умолчанию, но для сборки сайта понадобятся:

Сборка

Перед тем как начать сборку документации, может возникнуть несколько требований для сборки, если необходимая версия интерпретатора Python в вашей системе называется не "python". Если в вашей системе интерпретатора Python называется "python", то вы можете просто пропустить эту секцию.

Во-первых, скопируйте стандартные настройки:

% cd AROS/documentation/scripts/config
% cp defaults user

Далее, отредактируйте файл user и удостоверьтесь в том, что переменные правильны для вашей системы. В качестве примера конфигурационного файла можете посмотреть на этот:

PYTHON=python

Здесь PYTHON обозначает название интерпретатора Python в вашей системе. Оно также может быть задано в виде абсолютного пути. В некоторых системах может понадобиться заменить его на python2 или python2.2.

Цели

Цель - директория, содержимое которой используется для создания документации при помощи скриптов.

Сейчас поддерживаются 2 цели:

  • www

Из содержимого этой директории генерируется сайт AROS, который включает в себя всю документацию, новости, галереи изображений с подписями и информацию о состоянии. Документация хорошо интегрируется с остальным содержимым сайта.

  • html

Из содержимого этой директории генерируются самостоятельные HTML-страницы документации, пригодные для чтения в оффлайн и собранные в пакет документации.

Процедура сборки

Для сборки из определённой директории, просто вызовите скрипт сборки с указанием имени директории в качестве первого аргумента. Необходимо чтобы текущая директория была корнем дерева документации. Например, для сборки сайта сделайте следующее:

> cd AROS/documentation
> ./build www

Если вы хотите собрать HTML-документацию отдельно:

> cd AROS/documentation
> ./build html

Подсказка: добавление языкового суффикса (например, en, du или it) после имени цели сгенерирует страницы только для указанного языка. Все пропущенные или не переведённые страницы будут также заменены на их англоязычные копии. Как следствие, сильно уменьшится время компиляции.

> cd AROS/documentation
> ./build www du

Сгенерированные файлы будут помещены в ../bin/documentation/<имя-приёмника>, например, ../bin/documentation/www для цели www. Файлы на соответствующих языках будут помещены в ../bin/documentation/<target-name>/<название-языка>.

Дополнительно существует цель clean, которая полностью очищает директорию ../bin/documentation.

Примечание

На текущее время в исходных директориях генерируется довольно много промежуточных файлов, поэтому вы не можете разместить их в файловой системе, доступной только для чтения. Если вы зафиксировали исходники из SVN, то не надо беспокоиться, сгенерированные файлы игнорируются.

Copyright © 1995-2024, The AROS Development Team. Все права защищены.
Amiga© является торговым знаком Amiga Inc. Все прочие торговые знаки принадлежат их собственникам.