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').

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

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)

Configuring the Maven pom files

<properties>
  [...] 
  <docs.m.forms.version>1.0</docs.m.forms.version>
  <docs.m.forms.relPath>blocks/forms/${docs.m.forms.version}/</docs.m.forms.relPath>     
</properties>

 <collection>
    <name>cdocs-forms</name>
    <path>${docs.m.forms.relPath}</path>
  </collection>

• 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)

    <build>
        <plugins>
            <plugin>
                <groupId>org.daisycms</groupId>
                <artifactId>daisy-maven-plugin</artifactId>
                <configuration>
                    <navDocId>1152</navDocId>
                    <collection>cdocs-forms</collection>                   
                    <skipFirstNavigationDocumentLevel>true</skipFirstNavigationDocumentLevel>
                </configuration>
            </plugin>
        </plugins>
    </build>

• 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.

  <distributionManagement>
    <site>
      <id>website</id>
      <url>${docs.deploymentBaseUrl}/${docs.m.forms.relPath}</url>
    </site>
  </distributionManagement>
  <properties>
    <docs.name>Cocoon Forms</docs.name>    
    <docs.version>${docs.m.forms.version}</docs.version>
  </properties>

• 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.

    <module>../blocks/cocoon-forms/cocoon-forms-impl</module>