Cocoon Site Overview

Recently changed documents

ID	Name	Version State	Version Creation Time	Actions

Documentation of the Cocoon documentation system

Welcome to the Cocoon documentation. This site integrates all available pieces of the Cocoon documentation. This document contains some short explanations of frequent documentation related tasks and an overview of the documentation architecture.

How to ...

add a document?

If you want to add a new document, go to the site at http://cocoon.zones.apache.org/daisy/ where you want to add the document and select "New Document". Choose "Cocoon Document" as type and start editing. Finally you have to add the document to the navigation document so that it will appear in the menu structure.

add a news item?

Basically it is the same as "Adding a document", except that you choose "News Item" as document type. At the website the 7 latest news items are shown. Since the news items are selected by a query, they don't need to be added to a navigation document.

add the documentation of a deployment unit?

This guide explains in detail how to document a new deployment unit (e.g. you want to add documentation for another block).

Publishing

Publishing documents to http://cocoon.apache.org

You have successfully created a new document, e.g. a new news item? And now you want to publish it to cocoon.apache.org? This task has to be performed from the shell at cocoon.zones.apache.org. Login via SSH (if you don't have a user, contact private@cocoon.apache.org) and switch to the "maven" user by "sudo su - maven" as it already is configured correctly to access the Daisy repository and it has all environment variables set correctly. Then go to /home/maven/site-generation and call the script "./update.sh" from there. This will recreate the documentation and deploy it to /home/maven/site-generation/site which is a SVN working copy of https://svn.apache.org/repos/asf/cocoon/site. Then do use svn stat to see what has changed and commit the changes. That's all. Within the next 4 hours, the changed site will be deployed to http://cocoon.apache.org.

In short all the required steps to re-publish the Cocoon documentation are:

ssh cocoon.zones.apache.org
sudo su - maven
cd site-generation
./update.sh
cd site
svn stat
svn add [files]
svn commit --username [username] --password [password]

We haven't been using the new documentation system for publishing to cocoon.apache.org yet. That's the reason why the scripts are not available.

Automatic publishing - Staging zone

At http://cocoon.zones.apache.org/dev-docs/ you can find the staging zone of our documentation. It is recreated every 4 hours. If you don't want to wait for some reason, go to the Continuum web interface, and build the "$cdocs" project there, which will build and deploy the documentation. You have to log in as user "admin". The password can be found at /home/maven/password.txt@cocoon.zones.apche.org.

How does the documentation system work?

The Daisy part

The main rule of our documentation system is that every deployment unit has its own documentation. As we use the Daisy CMS this is achieved by having

•  one collection
•  one navigation document and
•  one site

per deployment unit .

In order to get an overview of all the pieces that are available, we have a special site "cdocs" at http://cocoon.zones.apache.org/daisy/cdocs/. There you will find everything that is part of the Cocoon documentation in some way. Currently these are three parts:

• Cocoon Book: The Cocoon book includes all the documentations of our deployment units (e.g. Cocoon Core, Cocoon Forms, etc.) and can be used to use the Daisy book feature of creating e.g. a PDF of the complete docs.
• Website only: There you will find all the documents that are only avaiable on our website because it doesn't make sense to include them into our Cocoon Book. Examples are the main site (http://cocoon.apache.org) or the intermediate sites (http://cocoon.apache.org/blocks/).
• Administration: There you will find documents that make the use of our documentation system easier. These are things like links to all navigation documents, information about how to create a static version of the docs or how to add new documentation for a deployment unit.

The publishing part

The document extraction is done based on the Maven site generation tools. The documents are extracted from the Daisy repository server by the Daisy Maven plugin (see http://svn.cocoondev.org/repos/daisy/contrib/daisy-client-apps/trunk/daisy-maven-plugin/). The most important configuration parameters of the Daisy Maven plugin is the navigation document that is taken as starting point of the extraction process.

The plugin creates in src/site the document structure as expected by the Maven Site plugin. By using the Cocoon Site Skin plugin (http://svn.apache.org/repos/asf/cocoon/trunk/site/cocoon-maven-site-skin/) the final documents are created.