This info is for Cocoon committers who need to update Cocoon's 2.1 website.

FIXME: Some out-of-date content

See this dev discussion about the issue of the Daisy on the Cocoon zone server being down, and so Forrest cannot generate the docs.

http://s.apache.org/resurrect-cocoon-docs Date: 17 Jan 2012 Subject: resurrect the Cocoon documentation

Some of the content below is still relevant.

See also

NOTES FOR QUICK UPDATE OF c.a.o/2.1/

Get the docs that are generated daily from Daisy by Forrestbot. Commit these docs to the SVN which holds the Cocoon website. Here is how ...

That is it. There is a cronjob on the server to do 'svn update'.

See below for further information.

Verifying The Generated Site

The above site package is generated by Forrest every 12 hours. You only need to update the site manually (see below) if you don't want to wait for the next automated update.

You can preview what is in the download by looking at the Forrest Zone

You can also verify that there are no broken links by looking at the broken links xml file (it should be empty of course).

WHERE DOES THE WEBSITE CONTENT COME FROM?

The website content is held in the https://svn.apache.org/repos/asf/cocoon/site repository.

All generated documents are held in the "site" sub-directory.

The source for the top-level website is in the "src" sub-directory containing the content that we write (in xdoc format), and the corresponding website pages (generated by Forrest) are committed to the "site" sub-directory, to make it easy to update or restore the content on the live web server. This means that any manual changes to html pages in the site subdirectory are lost when the site is regenerated using Forrest.

The source of http://cocoon.apache.org/ index page, for example, is found at http://svn.apache.org/repos/asf/cocoon/site/src/documentation/content/xdocs/index.xml

HOW ABOUT DAISY?

Since 2.1.8, the documentation (apart from the top-level website pages described above) is written using Daisy at http://cocoon.zones.apache.org/daisy/legacydocs/654.html and Daisy-generated pages are processed by Forrest (using forrest trunk) to generate the static pages (still in experimental phase).

If you want to build the site locally, then get these two repositories and follow the detailed instructions below.

HOW TO UPDATE THE APACHE COCOON WEBSITE

See the overview above. Committers should let forrestbot do the work, and use the "quick update" method of committing the final docs to cocoon/site SVN.

Here are the details ...

Forrest notes

  • Use Forrest-trunk for both the top-level docs and the 2.1 docs - https://svn.apache.org/repos/asf/forrest/trunk
  • Out of the box, Forrest will not render PNG images in PDFs (due to license restrictions on Jimi). You need to download Jimi from Sun. Copy the JimiProClasses.zip file to $FORREST_HOME/lib/optional/jimi-1.0.jar

For review purposes the Forrestbot generates the 2.1 docs every day. See Forrest zone. However, publishing the website is still a manual process done occasionally by committers.

Process notes for Cocoon Release day

  • Edit /2.1/index.html and /2.1/news.html via Cocoon's Daisy.
  • Edit /news/index.xml via cocoon-site SVN (see B below).
  • Follow the notes below to generate and update.
  • Pack the docs for 2.1 download and place beside the release. Do ssh to forrest.zones and zip them from the forrestbot build ($DOC_ROOT/ft/build/). direct download
  • Update the 2.1 website (see C below).
  • Regenerate the Javadocs (see A below).

General notes

A) Checkout the cocoon-site SVN

If you have checkout already, just update it. This repository holds the generated docs for both the top-level website and for each set of version-specific docs. It also holds the source xdocs and the Forrest config files for the top-level website.

NOTE: cocoon-site is more than 60 Mb. You can checkout only part of it, say, for Cocoon 2.1, cocoon-site/site/2.1 (35Mb)

NOTE: The javadocs are not stored in the cocoon-site SVN. They can easily be regenerated. Use scp to copy them to the website.

(smile) Generate top-level site

For the top-level website, just do the command 'forrest' in the top-level cocoon-site directory. After generation is complete, the site will be ready at the build/site/ directory. Use forrest-trunk.

View the generated docs to be sure that everything is as you would expect.

Now copy the generated docs:

  • cd cocoon-site
  • cp -Rf build/site/* site

Note: There is a glitch, probably because the 2.1 site has changed its presentation and the top-level site config is not in sync. So only copy the *.html *.pdf

C) Generate the 2.1 docs

  • cd cocoon-daisy-to-docs
  • forrest
  • cp -Rf build/site/2.1/* ../cocoon-site/site/2.1

Note: That is taking too much time locally (over a minute per doc). A good solution is to copy the tar file of generated docs from the forrest zone (see above) to your local machine. Look our for line-endings if you are not on unix.

D) Upload site into SVN

Ensure that your cocoon-site is up-to-date (do 'svn update' again). Copy the generated files to the relevant directory under cocoon-site/site/ and then do the usual SVN stuff: 'svn status' 'svn add' 'svn diff' 'svn commit'

E) Update site on the server

Steps are:

  • ssh people.apache.org
  • Check your environment: make sure your umask is set to 0002 ('umask 0002' in ~/.profile, or use the "umask" command)
  • cd /www/cocoon.apache.org/
  • svn update
  • Double-check that all files you left over there are g+w so others can work from where you finished.

Done!

Other notes:

  • There is a .htaccess file to redirect the old URLs from xml.apache.org/cocoon/* to the current distribution, e.g. /2.1/ ... so when v2.2 comes you need to edit cvs xml-site/targets/cocoon/.htaccess and manually at /www/xml.apache.org/cocoon/.htaccess
  • The files that create the dist/cocoon/ directory are not all under source control (Todo: they should be), so edit those files in place at /www/www.apache.org/dist/cocoon/*.html (don't forget the .htaccess files). Other files like "mirror.html" are under source control, so edit them in the cocoon-site module, then 'ssh cvs.apache.org; cd /www/cocoon.apache.org/; svn update mirror.html'.
  • No labels