cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Cocoon 2.2 documentation
Date Fri, 22 Sep 2006 15:46:15 GMT

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 
private@cocoon.apache.org 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

Mime
View raw message