Sławomir Czerwiński

Niezależnie od tego, czy projekt publikowany jest szerszej grupie osób, czy tylko pracownikom jednej firmy, przydaje się strona WWW, na której można znaleźć szczegóły techniczne programu bądź biblioteki. Strona taka powinna zawierać dokumentację kodu (JavaDoc), wyniki testów, sposób użycia biblioteki, informacje o położeniu repozytorium itp. W przypadku wtyczki Maven bardzo pomocna jest lista dostępnych zadań czy parametrów. Mniej zaawansowani użytkownicy będą poszukiwać również przykładów, dzięki którym łatwiej im będzie skorzystać z przygotowanych rozwiązań.

Apache Maven wspomaga tworzenie stron projektów oraz dołączanie do nich wygenerowanych raportów. Niniejszy wpis stanowił będzie wprowadzenie do zagadnienia, którego pełne omówienie mogłoby samo w sobie być tematem do napisania obszernej książki.

pom.xml

Do projektu LaTeX MetaPost Maven Plugin dodam trzy wtyczki raportujące:

maven-plugin-plugin

generuje dokumentację wtyczki Maven, wraz z opisem dostępnych zadań oraz konfiguracji;

maven-surefire-report-plugin

pozwoli utworzyć stronę zawierającą zestawienie wyników testów;

maven-javadoc-plugin

dołączy do strony wygenerowane raporty JavaDoc.

W tej chwili pominę zaawansowaną konfigurację raportów – jedyny ustawiony parametr pozwoli ograniczyć dokumentację JavaDoc do elementów publicznych (linie 19–21):

<project>
  […]
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-plugin-plugin</artifactId>
        <version>2.5.1</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-report-plugin</artifactId>
        <version>2.5</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.6.1</version>
        <configuration>
          <show>public</show>
        </configuration>
      </plugin>
    </plugins>
  </reporting>
  […]
</project>

Czas na dodanie kilku bardziej zrozumiałych informacji na temat samej wtyczki. Obecnie wiadomo jedynie, że projekt nazywa się latex-metapost-maven-plugin i należy do grupy pl.info.czerwinski. Jednak Maven pozwala zdefiniować nazwę, adres strony internetowej, a nawet krótki opis:

<project>
  […]
  <name>LaTeX MetaPost Maven Plugin</name>
  <url>http://mojo.czerwinski.info.pl/latex-metapost-maven-plugin/</url>
  <description>
    LaTeX MetaPost plugin for use with Codehaus LaTeX Maven Plugin.
  </description>
  […]
</project>

Kolejnym parametrem będzie rok rozpoczęcia prac nad projektem, pozwalający na utworzenie informacji o prawach autorskich:

<project>
  […]
  <inceptionYear>2010</inceptionYear>
  […]
</project>

W przypadku wtyczki opublikowanej do wykorzystania przez dowolne podmioty, przyda się informacja o licencji lub licencjach. Maven pozwala na dołączenie treści z dowolnej strony internetowej, na przykład:

<project>
  […]
  <licenses>
    <license>
      <name>Creative Commons License (BY-NC-SA)</name>
      <url>http://creativecommons.org/licenses/by-nc-sa/3.0/</url>
    </license>
  </licenses>
  […]
</project>

Szczególnie w środowisku OpenSource, ale także w przypadku publikacji produktu dla wewnętrznych potrzeb organizacji, przydatna jest informacja o systemie zarządzania zgłoszeniami (linie 3–6) oraz repozytorium kodu (linie 8–11):

<project>
  […]
  <issueManagement>
    <system>redmine</system>
    <url>http://redmine.czerwinski.info.pl/projects/latex-mp-mvn-plugin</url>
  </issueManagement>

  <scm>
    <connection>scm:git:http://git.czerwinski.info.pl/latex-metapost-maven-plugin/</connection>
    <url>http://redmine.czerwinski.info.pl/projects/latex-mp-mvn-plugin/repository</url>
  </scm>
  […]
</project>

Na samym końcu warto też zadbać o samych autorów oraz organizację dostarczającą dane rozwiązanie. Pozwalają na to takie parametry jak developers czy organization (można też zdefiniować współpracowników – contributors):

<project>
  […]
  <organization>
    <name>Sławomir Czerwiński</name>
    <url>http://czerwinski.info.pl/</url>
  </organization>

  <developers>
    <developer>
      <name>Sławomir Czerwiński</name>
      <url>http://czerwinski.info.pl/</url>
      <email>slawomir@czerwinski.info.pl</email>
      <roles>
        <role>Project Manager</role>
        <role>Developer</role>
      </roles>
    </developer>
  </developers>
  […]
</project>

Już w tej chwili, za pomocą polecenia mvn site, można wygenerować witrynę projektu. Ja jednak chciałbym dodać jeszcze kilka niestandardowych stron.

src/site/site.xml

Plik site.xml definiuje zawartość znajdującego się po lewej stronie menu. Poniżej znajduje się przykład takiego pliku:

<?xml version="1.0" encoding="UTF-8"?>
<project name="LaTeX MetaPost Maven Plugin">
  <body>
    <menu name="Overview">
      <item name="Introduction" href="index.html"/>
      <item name="Goals" href="plugin-info.html"/>
      <item name="FAQ" href="faq.html"/>
    </menu>

    <menu ref="reports"/>
  </body>
</project>

Dołączone w linii 10 menu reports zawiera wszystkie wygenerowane raporty oraz główne informacje dotyczące projektu. Strona plugin-info.html (linia 6) pochodzi z jednego z tych raportów – generowanego przez maven-plugin-plugin.

Pozostałe dwa elementy menu – Introduction oraz FAQ – będą utworzone ręcznie.

src/site/apt/index.apt

Maven pozwala na tworzenie stron w różnych formatach, a następnie generowanie z nich plików HTML. Do utworzenia strony startowej (Introduction) użyję jednego z  takich formatów – APT, którego dokładny opis można znaleźć na stronie Maven.

Na mojej stronie głównej znajdzie się jedynie podstawowy opis wtyczki oraz lista (dużo powiedziane) zadań Mojo:

 ------
 Introduction
 ------
 Sławomir Czerwiński
 ------
 2010-03-01
 ------

LaTeX MetaPost Maven Plugin

  LaTeX MetaPost plugin dedicated for use with
  {{{http://mojo.codehaus.org/latex-maven-plugin/index.html}LaTeX Maven Plugin}}.

* Goals Overview

  * {{{compile-mojo.html}latex-metapost:compile}} compiles MetaPost files.

src/site/fml/faq.fml

Ogromne wsparcie dla strony pytać i odpowiedzi (ang. Frequently Asked Questions) zapewnia format FML, będący po prostu specyficznym plikiem XML.

Jak dotąd nikt nie zadał mi żadnego pytania dotyczącego LaTeX MetaPost Maven Plugin, więc pozostawię jedynie przykładowe pytanie Question?:

<?xml version="1.0" encoding="UTF-8"?>
<faqs id="FAQ" title="Frequently Asked Questions">
  <part id="General">
    <faq id="question">
      <question>Question?</question>
      <answer>
        <p>
          Answer
        </p>
      </answer>
    </faq>
  </part>
</faqs>

Generowanie strony

Aby wygenerować witrynę projektu, należy wykonać polecenie mvn site. Aby żadna strona nie pozostała w starej wersji, zalecam wcześniej użyć mvn clean.

Menu strony zawiera kolejno utworzoną ręcznie sekcję Overview, oraz wygenerowaną automatycznie Project Documentation. Ta druga zawiera dwie grupy elementów – Project Information oraz Project Reports – gdzie znaleźć można wszelkie dodane do projektu informacje oraz raporty, takie jak dokumentacja JavaDoc czy rezultaty testów.

Podsumowanie

Do witryny można dodać wiele własnych stron, napisanych w formacie APT lub Xdoc, własne arkusze stylów (CSS) czy też obrazki. Nie będę tutaj opisywał każdej możliwości z osobna, ale prawdopodobnie w przyszłości pojawią się nowe wpisy, dostarczające kolejnych informacji o tworzeniu stron projektów Maven.