Over the last couple of months we made good progress to split up Cocoon into
smaller chunks. One of the things that still lacks behind is our documentation
which isn't related to the new structure.
A couple of weeks ago I started to work on the documentation part to bridge this
gap. I've had three main goals:
- each deployment unit should get its own documentation
- it should be still possible to read the complete Cocoon documentation
as one big document
- publishing docs should be very simple (again)
What have I done so far?
------------------------
In short, I created a new Daisy site at
http://cocoon.zones.apache.org/daisy/cocoon-documentation/ that contains all
docs for Cocoon 2.2 and its blocks and Maven plugins. Then I wrote a Daisy Maven
plugin that extracts the documents from the Daisy documents repository and use
the Maven site plugin to generate the final docs.
I also wrote a Cocoon skin for Maven which is a mixture of the current Maven
skin and the Cocoon 2.1 skin.
If you're interested what the result looks like, you can find a prototype at
http://people.apache.org/~reinhard/cocoon-docs/. (Please note that the current
structure is far from being complete.)
- o -
For those of you, who are interested in more details about how things work
together, please keep on reading. Thanks to the others - please jump to the last
paragraph "Next steps".
As a first step was I created a new site in Daisy: You can find it at
http://cocoon.zones.apache.org/daisy/cocoon-documentation/1201.html.
If you follow the link you will see that, thanks to the flat documents structure
of Daisy, it mostly reuses already existing documents. The only thing that's
different is some new navigation documents. Each node of the following tree is a
navigation document:
* Cocoon Documentation
* Cocoon Book
* Cocoon Core
* Cocoon Blocks
* Forms
* Website only
* Cocoon Main Site
* Cocoon Blocks Site
* Administration
I made this design decision because this makes it possible to
- create a PDF document that contains the complete documentation (or
just a part of it)
- assign a navigation document to a module
As you can see, by using Daisy this way, the two first goals of my list above
are reached. The missing goal is documentation publishing. For this purpose I
wrote a Maven plugin[1] that is e.g. configured like this[2]:
<plugin>
<groupId>org.daisycms</groupId>
<artifactId>daisy-maven-plugin</artifactId>
<version>1.0.0-SNAPSHOT</version>
<configuration>
<navDocId>1152</navDocId>
<collection>cdocs-forms</collection>
</configuration>
</plugin>
This particular plugin configuration could be used by the forms-impl module to
create the cforms documentation. This doesn't replace the Maven site plugin but
is an execution step before the site rendering. The Daisy Maven plugin reads the
"navDocId" parameter and extracts all documents that are refered from there,
transforms the Daisy documents to Maven xDocs and takes care that all links are
rewritten correctly[3].
After the docs have been generated, the Maven site plugin uses them and creates
the documentation by using the Velocity template from the Cocoon skin for Maven.
The final docs can be found in /target/site. By using the site-deploy goal the
docs can be copied to locations that are available via file:/, scp:/ or ftp:/
protocol. For our purpose the file:/ protocol is good enough as we still want
copy the docs to /cocoon/site/ in our SVN. This way we follow the Apache policy
to keep the docs in SVN and don't have any problems with different versions of
our docs. Because what do we do, if we release Cocooon Forms 2.0? The answer is
simple as we only have to put our docs into /cocoon/site/blocks/forms/2.0 in the
future - the 1.0 docs remain where they are and are simply not changed anymore.
You want to try out documentation generation yourself?
------------------------------------------------------
That's really simple now! The first time you want to use the plugin from a
particular machine, you have to configure ~/.m2/settings.xml by configuring the
credentials for our Daisy repository:
<settings>
<servers>
<server>
<id>cocoon-daisy</id>
<username>[user with admin rights]</username>
<password>[password]</password>
</server>
</servers>
</settings>
Then move to e.g. cocoon/trunk/site and run "mvn site" from there. That's it.
(For some reason repository access requires an admin user - if you're a Cocoon
committer and want to try out the plugin, just drop a note to
[EMAIL PROTECTED] with your request.)
You want to add docs for a particular module?
---------------------------------------------
First you have to create a new collection for the new sub documentation with the
cdocs prefix (you need admin rights for this.) Then create a navigation document
and add it to the just created collection. I recommend that you use the
BookDefinition instead of the NavigationDocument type which is more powerful as
it allows the creation of books.
Then you have to import your navigation document within some already existing
navigation document (see the tree of navigation docs above). Now you can add
docs to your navigation doc as you wish. For the purpose of correct link
rewriting, you have to add the document to the collection that you created above.
In order to export the docs you have to configure the pom.xml of the navigation
document by adding the daisy-maven-plugin and the maven-site-plugin to the build
section of the pom:
<distributionManagement>
<site>
<id>website</id>
<url>${docs.deploymentBaseUrl}/[relativePath]/${docs.version}/</url>
</site>
</distributionManagement>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.daisycms</groupId>
<artifactId>daisy-maven-plugin</artifactId>
<configuration>
<navDocId>[docId of the navigation document]</navDocId>
<collection>[collection name]</collection>
</configuration>
</plugin>
</plugins>
</build>
<properties>
<docs.name>Cocoon Forms</docs.name>
<docs.version>1.0</docs.version>
</properties>
As you can see, you can set a version number for the documentation too as the
<version> attribute isn't appropriate for this because we don't want to release
a completly new set of docs for a new patch release.
As there might be links between docs from different locations, you have to
configure a new collection within the collections configuration of the root
pom.xml of Cocoon:
<collection>
<name>[collection name]</name>
<path>[relative path to the deployment location]</path>
</collection>
This configuration is used to rewrite links correctly.
Next steps
----------
First, thanks for reading so far! If you agree, I would like that we use the new
documentation structure in Daisy for our Cocoon 2.2 docs and polish the Maven
skin. If we like we can even use Continuum to deploy our docs at
cocoon.zones.apache.org which would help us to find out how the result docs look
like.
A lot of stuff that we could trigger at the GT and I'd happily introduce to
everybody who is interested in helping out.
Reinhard
[1] For those of you that don't like Maven: It should be very simple to reuse
the plugin code to e.g. write an Ant task ;-)
[2] The plugin configuration of the root pom.xml contains some more parameters:
<plugin>
<groupId>org.daisycms</groupId>
<artifactId>daisy-maven-plugin</artifactId>
<version>1.0.0-SNAPSHOT</version>
<configuration>
<!-- global parameters -->
<repoUrl>http://cocoon.zones.apache.org:9263</repoUrl>
<editUrl>http://cocoon.zones.apache.org/daisy/
cocoon-documentation/</editUrl>
<daisyServerId>cocoon-daisy</daisyServerId>[3]
<author>The Cocoon Community</author>
<collections>
<collection>
<name>cdocs-site-main</name>
<path>/</path>
</collection>
<collection>
<name>cdocs-site-blocks</name>
<path>blocks/</path>
</collection>
<collection>
<name>cdocs-core</name>
<path>core-modules/core/2.2/</path>
</collection>
<collection>
<name>cdocs-forms</name>
<path>blocks/forms/1.0/</path>
</collection>
<collection>
<name>cdocs-template</name>
<path>blocks/template/1.0/</path>
</collection>
</collections>
</configuration>
</plugin>
The username and the password of the Daisy repository server (cocoon-daisy) have
to be configured in the user's settings.xml as server elements.
[3] I donated the plugin to the Daisy project. See
http://svn.cocoondev.org/repos/daisy/contrib/daisy-client-apps/trunk/ and
http://www.apache.org/~reinhard/m2-snapshot-repository where I published a
recent snapshot.
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
___________________________________________________________
Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
