Руководство по документированию AROSПредупреждение Этот документ не окончен! Вполне возможно, что многие части устарели, содержат некорректную информацию или полностью отсутствуют. Если вы хотите исправить их, пожалуйста сообщите нам. Это руководство описывает систему документирования AROS. Оно предназначено как для тех, кто пишет документацию, так и для разработчиков, желающих описать или исправить саму систему. Руководство составлено из трёх частей: общего введения в систему, как использовать её для написания документации и наконец, технические замечания и спецификации. Не считая информации о пользовании самой системой, вторая глава также содержит общие рекомендации, которым надо следовать при написании документации к AROS. ВведениеДокументация жизненно важна для любого проекта, делая его пригодным к использованию. Обычно, в таких ограниченных в количестве разработчиков проектах, как наш, документация пишется в последнюю очередь или просто отсутствует. Также, большинство программистов не настолько хороши в написании документации, как в программировании, поэтому то, что уже написано обычно не очень удобочитаемо. Необходимо объединить усилия разработчиков и пользователей в документировании для достижения цели под названием "полностью документированная AROS". Так что, если вы знаете пользователей, которые могут нам помочь, зовите их! :) Поправить: Написать подробнее? Написание документацииФормат документации, которым мы пользуемся, называется reStructuredText (или ReST для краткости), разработанный проектом Docutils. ReST лёгок для чтения и записи, соответствует принципу WYSIWYG (что-ты-видишь-это-то-что-получишь), расширяем, синтаксис основан на разметке простого неформатированного текста. Его можно назвать гибридом явного и неявного синтаксиса разметки, что делает его лёгким для изучения и весьма удобочитаемым, но при этом он остаётся мощным и расширяемым. Введение в reStructuredText содержит несколько хороших замечаний о целевом синтаксисе. Так как основой является неформатированный текст, то его очень легко изучить, просто просматривая существующую документацию и руководствуясь здравым смыслом, но всё же рекомендуется прочитать хотя бы Пример использования reStructuredText перед началом работы над документацией к AROS. Для получения более подробной информации о формате рекомендуются для прочтения следующие документы: Архив документацииДля того, чтобы изменять или писать документацию вам надо получить ветку 'documentation' из дерева версий Subversion. Ветка с архивом документов содержит:
Примечание Название '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://www.aros.org спустя несколько часов после их передачи. Технические замечанияБазы данныхЕсть несколько маленьких баз данных, которые вы можете найти в директории 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 "с нуля" вам потребуется следующее:
Для сборки сайта дополнительно понадобится графическая библиотека:
В MacOS X интерпретатор Python предустановлен по умолчанию, но для сборки сайта понадобятся:
СборкаПеред тем как начать сборку документации, может возникнуть несколько требований для сборки, если необходимая версия интерпретатора Python в вашей системе называется не "python". Если в вашей системе интерпретатора Python называется "python", то вы можете просто пропустить эту секцию. Во-первых, скопируйте стандартные настройки: % cd AROS/documentation/scripts/config % cp defaults user Далее, отредактируйте файл user и удостоверьтесь в том, что переменные правильны для вашей системы. В качестве примера конфигурационного файла можете посмотреть на этот: PYTHON=python Здесь PYTHON обозначает название интерпретатора Python в вашей системе. Оно также может быть задано в виде абсолютного пути. В некоторых системах может понадобиться заменить его на python2 или python2.2. ЦелиЦель - директория, содержимое которой используется для создания документации при помощи скриптов. Сейчас поддерживаются 2 цели:
Из содержимого этой директории генерируется сайт AROS, который включает в себя всю документацию, новости, галереи изображений с подписями и информацию о состоянии. Документация хорошо интегрируется с остальным содержимым сайта.
Из содержимого этой директории генерируются самостоятельные 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-2009, The AROS Development Team. Все права защищены. Amiga© является торговым знаком Amiga Inc. Все прочие торговые знаки принадлежат их собственникам. |