Документирование вашего проекта с использованием справочной системы Eclipse

Создание удобной и доступной для поиска справочной документации

Платформа Eclipse, предоставляющая очень мощную IDE, имеет свою собственную справочную систему, основанную на таблицах содержания в формате XML, ссылающихся на HTML-файлы. Что не является очевидным - вы не должны писать подключаемые модули Eclipse для использования этой системы. Любой проект может использовать усеченную версию платформы для предоставления профессиональной, удобной и доступной для поиска документации. Такая система документации с успехом используется во множестве проектов, включая такие большие как WebSphere® Application Server.

Артур Бар, Инженер-программист, IBM

Артур Бар (Arthur Barr) - инженер-программист исследовательской лаборатории IBM Hursley, расположенной в Великобритании. Он воплотил идеи этой статьи в проекте "Business Integration for Games", над которым он, возможно, работает в настоящее время. Вы можете связаться с Артуром по адресу arthur.barr@uk.ibm.com.



29.01.2004

Когда вы вызываете справочную систему Eclipse, (посредством Help > Help Contents), вы фактически запускаете встроенный сервер Apache Tomcat. Открывается окно, размещенное в Web-браузере и показывающее определенную страницу на этом сервере (смотрите рисунок 1). В левой части располагается индекс в виде развертывающегося списка, а в правой части - HTML-документация. По этой документации можно осуществлять поиск (благодаря поисковой системе Apache Lucene). Поскольку используется Tomcat, вы не ограничены форматом HTML; например, вы можете применять JSP для динамического изменения документации (хотя ниже мы обсудим возможные причины, чтобы этого избегать).

Рисунок 1. Пример справочной системы Eclipse
Пример справочной системы Eclipse

Подключаемый модуль документации "Здравствуй, мир!"

Документация разделяется на "книги", и вы можете иметь столько книг, сколько захотите, в одном экземпляре справочной системы. Каждая книга написана в виде подключаемого модуля Eclipse, но, к счастью, объем работы здесь минимальный. Для написания простого подключаемого модуля вам нужен файл plugin.xml для описания модуля, который должен выглядеть аналогично представленному в листинге 1.

Листинг 1. Определение подключаемого модуля
<plugin name="Sample Documentation Plug-in" id="com.ibm.sample.doc"
   version="1.0.0" provider-name="IBM">
   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true" />
   </extension>
</plugin>

Измените name, id, version и provider-name подключаемого модуля на значения, соответствующие вашему проекту. Точка расширения org.eclipse.help.toc указывает на то, что это подключаемый модуль справочной системы. В качестве таблицы содержания для этого модуля указывается файл toc.xml; в этом файле находятся данные для иерархической информации в левой панели окна справочной системы Eclipse. Простой файл может содержать, например, данные, приведенные в листинге 2.

Листинг 2. Определение таблицы содержания
<toc label="Sample Documentation">
    <topic label="My Section" href="mySection.html">
        <topic label="Foo" href="foo.html"/>
        <topic label="Bar" href="bar.html"/>
    </topic>
</toc>

Пакетирование подключаемого модуля

Каждый элемент темы представлен в конечной документации в виде записи в списке навигации. Эти темы могут быть вложенными (они могут содержать другие темы) и каждая из них указывает на HTML или JSP-файл. После составления этих файлов все, что вам нужно - спакетировать все в структуру, показанную на рисунке 2 (обратите внимание, что название каталога подключаемого модуля соответствует его атрибутам id и version, определенным в plugin.xml).

Рисунок 2. Структура каталога подключаемого модуля
Структура каталога подключаемого модуля

Для удобства и для уменьшения размера файла Eclipse разрешает использование всей вашей реальной документации (HTML-файлов) в ZIP-файле под названием doc.zip, поэтому вы могли бы использовать структуру каталога, показанную на рисунке 3.

Рисунок 3. Альтернативная структура каталога подключаемого модуля
Альтернативная структура каталога подключаемого модуля

Просмотр вашей документации

Простейшим способом тестирования вашего подключаемого модуля является простое копирование каталога (указанного выше) в каталог plugins вашей платформы Eclipse, запуск Eclipse и выбор Help > Help Contents. Отобразится справочное окно, в которое будет добавлен ваш подключаемый модуль (примерно так, как показано на рисунке 1).

Использование IDE очень удобно для тестирования, но для применения без IDE документация должна быть более доступна, поэтому, что нам действительно нужно, - это запустить процесс в фоновом режиме, что позволит нам подключиться к нему в браузере. Этот режим работы известен под названием InfoCenter (смотрите рисунок 4). Инструкции по запуску процесса InfoCenter (основанного на Apache Tomcat) включены в справочную систему Eclipse (смотрите ссылку в разделе "Ресурсы" ниже). Обратите внимание также на инструкции по усечению системы Eclipse для получения только нужных вам функций.

Рисунок 4. InfoCenter в действии
InfoCenter в действии

Управление большими таблицами содержания

Если над вашим проектом работает несколько людей или проект имеет большой набор документации, обновление одного файла таблицы содержания (toc.xml) может стать непрактичным. Это можно изменить, добавив ссылку на вашу тему в главном файле toc.xml (смотрите листинг 3 для примера).

Листинг 3. Определение таблицы содержания
<toc label="Sample Documentation">
    <topic label="My Section" href="mySection.html">
        <topic label="Foo" href="foo.html"/>
        <topic label="Bar" href="bar.html">
            <link toc="bar-toc.xml" />
        </topic>
    </topic>
</toc>

Файл bar-toc.xml - это просто еще одна таблица содержания, которая должна иметь точно такой же формат, как и любой другой файл toc.xml. При просмотре документации нет разницы между использованием этого способа и прямого включения дополнительных элементов темы.


Генерирование автономного набора документации

Естественно, использование справочной системы Eclipse хорошо, если вы не беспокоитесь о распределении дополнительных 20 MB необходимого кода, но это не практично для маленьких проектов. Размещение InfoCenter на центральном сервере позволяет пользователям подключаться удаленно. Пользователи получают все преимущества использования справочной системы Eclipse (такие как поиск), но пользователи, не подключенные к серверу, остаются в затруднительном положении. Поэтому, в дополнение к использованию InfoCenter, полезно включать обычный HTML в загрузочный пакет. Поскольку вы не использовали какой-либо серверной технологии, например JSP, вы легко можете сгенерировать таблицу содержания в HTML-формате для замены XML-файла, используемого Eclipse. Вот почему нам нужен XSLT.

XSLT(eXtensible Stylesheet Language Transformations) - это технология, используемая для преобразования одной формы XML в другую, например в XHTML (более строго определенная XML-версия HTML). XSLT обеспечивает богатый и мощный язык для выполнения преобразований и сама является темой множества книг и статей, поэтому мы не будем углубляться в детали. В листинге 4 приведен пример простого преобразования файла toc.xml, интерпретирующего записи как вложенные HTML-списки. Обратите внимание, что это конкретное преобразование создает один HTML-файл для содержания полного набора документации, что будет громоздко для большого количества файлов. Следовательно, этот XSLT не будет работать, если вы разделили вашу таблицу содержания на несколько файлов.

Листинг 4. Пример XSLT для генерирования таблицы содержания в формате HTML
<?xml version="1.0"?>
<xsl:stylesheet
   version="1.1"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="html" indent="no" encoding="ISO-8859-1" />

<xsl:template match="toc">
   <html>
      <head />
      <body>
         <h1><xsl:value-of select="@label" /></h1>
         <ul>
            <xsl:apply-templates />
         </ul>
      </body>
   </html>
</xsl:template>

<xsl:template match="topic">
   <li>
      <xsl:choose>
         <xsl:when test="@href">
            <!-- Only add a hyperlink when there is something to link to ->
            <xsl:element name="a">
               <xsl:attribute name="href">
                  <xsl:value-of select="@href" />
                  </xsl:attribute>
               <xsl:value-of select="@label" />
            </xsl:element>
         </xsl:when>
         <xsl:otherwise>
            <xsl:value-of select="@label" />
         </xsl:otherwise>
      </xsl:choose>

      <!-- If there are any nested topics, then start a new sub-list ->
      <xsl:if test="descendant::topic">
         <ul>
            <xsl:apply-templates/>
         </ul>
      </xsl:if>
   </li>
</xsl:template>

</xsl:stylesheet>

Обработка файла toc.xml XSLT-процессором, например, Apache Xalan, с использованием приведенного выше XSLT выдаст в результате HTML-файл, который при просмотре в браузере выглядит примерно так, как показано на рисунке 5:

Рисунок 5. Генерирование index.html
Генерирование index.html

Заключение

Использование справочной системы Eclipse - это совершенно безболезненный способ разработки профессиональной, поддерживающей операции поиска документации, которая изумит ваших друзей и коллег. Если нет потребности в создании автономного набора документации, вам даже не нужно приближаться к XSLT; вы можете написать только два простых XML-файла и осчастливить мир документацией. Так вперед!


Загрузка

ОписаниеИмяРазмер
Образец кодаsource.zip---

Ресурсы

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Open source
ArticleID=97359
ArticleTitle=Документирование вашего проекта с использованием справочной системы Eclipse
publish-date=01292004