How to Work with the Pig Documentation

Forrest Set Up

Pig's official documentation is authored using Forrest. To commit documentation changes you must have Forrest installed and the forrest executable on your $PATH. Note that the current version of Forrest (0.8) does not work properly with Java 6, use Java 5 instead (make sure JAVA_HOME points to Java 5).

Documentation is of two types:

1. The website documentation (maintained separately in subversion, in the site branch)

2. The user documentation, versioned with releases (maintained separately in subversion, in the trunk )

Forrest Files

Forrest includes these files that you can modify for the Pig website docs or Pig user docs:

• /src/docs/forrest.properties – add plugins and set other properties here

• /src/docs/src/documentation/skinconf.xml – add CSS style changes, change logos, and set other switches here

• /src/docs/src/documentation//content/xdocs/site.xml – add or remove *.xml docs files here; controls which documents appear in the menu

• /src/docs/src/documentation//content/xdocs/tabs.xml – add or remove tabs here; controls which tabs appear on each page

Note: Some *.xml files in the Pig user docs require the Forrest simplified Docbook plugin. In the forrest.properties file, the plugin entry has been updated to include the Docbook plugin: project.required.plugins=org.apache.forrest.plugin.output.pdf,org.apache.forrest.plugin.input.simplifiedDocbook

Updating the Pig Website Documentation

Checkout the site branch: https://svn.apache.org/repos/asf/hadoop/pig/site/

To edit website doc files:

• Change to the directory that includes the *.xml files: site/author/src/documentation/content/xdocs.
• Edit the existing files or add new files

To view your edits using forrest:

• Change to the directory that includes the forrest.properties file: /site/author
• Run the "forrest run" command and leave it running ….

• Open a browser and enter http://localhost:8888/ - the /xdocs/index.xml page is displayed as index.html

• Make more changes to the XML doc files and then refresh the browser display to see your changes.

To create a local doc build:

• Change to the directory that includes the forrest.properties file: /site/author
• Run the "forrest" command (if the build fails due to broken links, the *.html and *.pdf ouptut will still be generated).
• To check the *.html and *.pdf output, move to this output directory: /site/author/build/site

Updating the Pig User Documentation

Checkout the trunk or relevant branch: http://svn.apache.org/repos/asf/hadoop/pig/trunk

To edit the user doc files:

• Change to the directory that includes the *.xml files: /trunk/src/docs/src/documentation/content/xdocs
• Edit the existing files or add new files

To view your edits using forrest:

• Change to the directory that includes the forrest.properties file: /trunk/src/docs/src/documentation/content/xdocs
• Run the "forrest run" command and leave it running ….

• Open a browser and enter http://localhost:8888/ - the /xdocs/index.xml page is displayed as index.html

• Make more changes to the XML doc files and then refresh the browser display to see your changes.

To create a local doc build:

• Change to the directory that includes the forrest.properties file: /trunk/scr/docs
• Run the "forrest" command (if the build fails due to broken links, the *.html and *.pdf ouptut will still be generated).
• To check the *.html and *.pdf output, move to this directory : /trunk/scr/docs/build/site

To build the user docs using ant:

• Change to the top directory of your structure: /trunk

• Run the "ant docs" command: ant docs -Djava5.home=java5_path -Dforrest.home=forrest_path

• To check the *.html and *.pdf output, change to this directory: /trunk/docs