Denn n i n s i s L und n b d erg r

Transcription

1 Dennis Lundberg

2 Agenda Creating a site using Maven involves making a lot of choices. Some of them are obvious, like choosing a suitable document format, while others are more subtle. This presentation we will go through these choices and provide some useful hints and tips along the way. The topics covered include "Beauty is skin deep", "In the greater schema of things" and "That will look bad on your report card!".

3 Warmup / hands up Which versions of Maven do you use? 2.0, 2.1, 2.2 and/or 3.0 Which version of the Site Plugin do you use? 2.0-beta, 2.0, 2.0.1, 2.1-SNAPSHOT or don't know Who is using the Site Plugin for production sites now? Who plan to use the Site Plugin for production sites later?

4 Structuringyour project +- pom.xml +- src/ +- site/ +- apt/ +- index.apt +- fml/ +- faq.fml +- resources/ +- logo.png +- xdoc/ +- other.xml +- site.xml Where in the POM do you configure the Site Plugin? In the <build> or the <reporting> section?

5 "I will always configure the Site Plugin in the <build> section of the POM"

6 What'syour format? APT (Almost Plain Text), XDoc, FML, Simplified DocBook, Confluence, Twiki and XHTML If you are starting from scratch use APT, unless you need special formatting then use XDoc Adding images and other resources, like PDF:s, Java files and properties files Handling your legacy html or shtml documents. Include them as resources (they won't be styled though) or convert them to XDoc.

7 Reusing your configuration Parent pom.xml and parent site.xml What goes in the parent site.xml and that goes in the child? Everything except navigation (menus + breadcrumbs) goes in the parent site.xml

8 My life as a site Understanding the site life cycle Phases: pre-site, site, post-site and site-deploy What's the difference between "mvn site" and "mvn site:site"?

9 That will look bad on your report card! Adding reports, but which ones? It depends on your audience: Your development team The Quality Assurance team Your pointy haired boss Your current customers Your potential customers Stock holders Venture capitalists The general public

10 Report Categories Project Info Reports: dependencies, issue tracking, license, plugins, project team, scm Source related: Javadoc, source cross reference, Surefire, Checkstyle, PMD, FindBugs, Clirr, Cobertura Change related: Changelog, Changes

11 "I will always specify a version for every reporting plugin"

12 Beware of the two-headed dragon Some pluginsare both build pluginsand reporting plugins. They need to be configured two times in your POM: once in the <build> section and once in the <reporting> section. Help is available at Look at the Project PluginsReport There is no <reporting>/<pluginmanagement> section in the POM!

13 "I will always configure reporting pluginsin the <reporting> section of the POM"

14 To version or not to version: that is the question When should you version the documentation? It depends on what you are building If it's a component or framework, then you should consider using versioned docs Example: Apache Commons

15 Beauty is skin deep If you are not satisfied with the default skin of your Maven generated site, you have three choices 1. Find another skin out there. Example: Apache Commons 2. Create a customized site.css file 3. Create your own skin. A skin consists of a site.css, a Velocity template and optionally a bunch of resources like images. Example: Mälardalen University

16 Usingmaven-default-skin

17 Usinga customskin

18 Dress meup There are two ways you can create your own skin 1. Bottom-up: Start with an existing skin and customize it until you're satisfied 2. Top-down: Start with an existing web design and insert Velocity parameters where you want them to be. Can you create A List Apart?

19 "I will always specify the version of the skin in site.xml"

20 In the greater schema of things Use the existing xml schemas for pom.xml, site.xml *.xdoc, *.fml and changes.xml Validation and code completion in your IDE All schemas can be found at mvn changes:changes-validate will validate the changes.xml file for you

21 Language support Supported languages for a Maven generated site: English plus 20 other languages What languages do you have on your Maven sites? What languages are supported by reporting plugins? Which reporting pluginssupports Swedish? Changes, Project Info Reports, Site Do we need to improve the support for Swedish in the reporting plugins? Which ones? Checkstyle?

22 Language and encodingtips Specifythe languageof your site: <locales>sv<locales> Specify your encoding using: <project>... <properties> <project.build.sourceencoding>iso </project.build.sourceencoding> <project.reporting.outputencoding>iso </project.reporting.outputEncoding> </properties>... </project>

23 The SitePlugin disected Doxia, Doxia Sitetools, maven-doxia-tools, Site Plugin maven-reporting-api, maven-reporting-impl, Project Info Reports Plugin, Reporting plugins Doxia is coupled to Maven core: 1.0/2.0, 1.1/2.1+ Theris no couplingto Doxiain Maven3

24 Because you have issues tm How many of you have had problems with the Site Plugin? How many were due to already reported issues? How many were not due to already reported issues? Did you report those issues?

25 I willreport issuesthat I findwith the SitePlugin to JIRA

26 Makingprogress? Change log: 2.0-beta-6 (43) November 2007, 2.0-beta- 7 (31) July 2008, 2.0 (24) March 2009, (3) July 2009 Road map: 2.1 (24) November 2009 Do you need a Site Plugin with inheritance bugs fixed or are you OK with upgrading to Maven 2.1 and using Site Plugin 2.1? How do you find the progress rate of the Site Plugin with regards to fixing bugs and adding new features? If it's too slow - how do we change it?

27 Read all aboutit The site for the Site Plugin Doxia reference docs Books: Better Builds With Maven (free download), Maven The Definitive Guide (free download, paper book), Apache Maven 2 Effective Implementation Is there enough documentation on the site for the Site Plugin? If not -what's missing?

28 Software tips Two very useful Firefox plugins: Web Developer Html Validator

29 EOP Q & A users@maven.apache.org dennisl@apache.org