Apache » Cocoon »

  Apache Cocoon

Apache Cocoon

How to create documentation for a deployment unit (e.g. a block)?

In Cocoon 2.2 each block has its own release cycle and also its own documentation set. This set is created through a separate site in Daisy. Each set has its own collection which is used by the Daisy export plugin in Maven to build the complete site, either locally at your hard disk, or at the official site.

The following steps outline the process to go through to create a block site. As an example we use the CForms block.

Create the collection

In Daisy, open Administration -> Manage collections.
Add a new collection for the block. The name should be cdocs-blockname, where blockname is the part of the name of the block after cocoon. Example: when the block is named cocoon-forms, the name of the collection should be cdocs-forms.
Note the id of the collection (in this case 7).

Create the navigation document

Each block has its own navigation document, which simplifies the packaging of the documation strictly for that block.

  1. In Daisy, create a New Document and choose type Book Definition.
  2. Set the name of the document to <user friendly name> Block [navigation]. For the CForms block that would be Forms Block [navigation].
  3. Go to the Misc tab and add the proper collection, in this case cdocs-forms.
  4. Underneath the root, add the toplevel folder for this block, by adding a new section node. Set the title to a user friendly name of the block. For the CForms block that would be Forms.
  5. Underneath this folder, add two documents, one is called Introduction, one is called Samples. You can create the documents by adding a new section node, and then select the "link to new document" button (second button after the document ID). Make sure these documents are also part of the proper collection, i.e. the cdocs-forms.
  6. Publish the document (mark a checkbox 'Publish changes immediately').
Note the id of the navigation document (in this case 1152).

Create a new Daisy site

Each block gets its own site in Daisy. Before adding documentation about the block, the site should be selected. This way all documents will automatically be in the proper collection.The steps below describe how to create a new Daisy site.
  1. Log in to cocoon.zones.apache.org with your username and password
  2. change to user daisy: sudo su - daisy
  3. cd daisywikidata/sites
  4. copy another block to the new block with blockname equal to the collection name. Example: cp -R cdocs-fop cdocs-forms
  5. cd into the new folder: cd cdocs-forms
  6. modify the siteconf.xml file:
    • change the title to match the name of the navigation document (without the [navigation] part), e.g. Forms Block
    • change the description to match the block name, e.g. Documentation of the Forms Block
    • change the navigationDocId to the id of the navigation document (in this case 1152)
    • change the homepageDocId to the id of the introduction document (in this case 489)
    • change the collectionId to the id of the new collection (in this case 7)
  7. save the file and logout of the server.

Add the navigation to the master navigation file

To show the block documentation in the total Cocoon documentation site, which is the source for the official documentation, you need to add the navigation document to the master navigation file. Do this step after creating the site, as a reminder that the site should be created as well.
These are the steps to take:
  1. In Daisy, go to the cdocs: Apache Cocoon site
  2. Select Administration in the navigation menu (so not on top!!!)
  3. You should now see a tree that represents the navigation tree of the cdocs site. This page is here only to provide convenient links to all the navigation documents.
  4. Edit the document to add the links to the navigation document. Make sure the block names are in alphabetical order and reflect the actual menu hierarchy.
  5. Save the document and select the Cocoon Book link.
  6. Edit the navigation document and add a new import navigation node with the id of the navigation document (in this case 1152)
Note: When adding documentation for the block, be sure you select the proper site first!

Configuring the Maven pom files

With the Daisy Maven plugin the information can be extracted from Daisy and built into the official site, either locally or at the official Cocoon documentation site.The steps below configure the Maven pom files to make this happen.

Configure the root pom.xml

Create two properties in trunk/parent/pom.xml. This is makes it easier to maintain these two pieces of information throughout the documentation generation process:
Open the pom.xml in the root and find the plugin with artifactId daisy-maven-plugin. Under collections add
Try to keep the collections in alphabetical order as well.

Configure the block pom.xml

  • Open the pom.xml file of the block, e.g. cocoon-forms-impl/pom.xml
  • Open a pom.xml file of a block that is already configured, e.g. cocoon-fop and copy the plugin with the groupID org.daisycms and artifactId daisy-maven-plugin
  • Add this to your pom file under <build>, <plugins>, if necessary create these tags. The build section should look like this (at least containing the daisy-maven-plugin part)
  • Change the navDocId to the id of the navigation document, in this case 1152
  • Change the collection to the name of the collection, in this case cdocs-forms
  • Add the distributionManagment part and the properties as well at the same level as the build tag.
    <docs.name>Cocoon Forms</docs.name>    
  • Change the path in the url to match the block name, here forms
  • Change the property docs.name to match the user friendly name of the block, here Cocoon Forms
  • Set the docs.version property to 1.0 initially and update it to reflect the documentation version.

Configure the site pom.xml

Open the pom.xml in the site and add a module to the section Cocoon Blocks:
Keep the modules in alphabetical order to ease maintenance.