Page History

...

Pig's official documentation is authored using Forrest. To commit documentation changes you must have Forrest installed and the forrest 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)in your $PATH.

Documentation is of two types:

1. The

...

Pig site documentation (maintained separately in subversion, in the site branch)

2. The Pig user documentation

...

(maintained separately in subversion, in the trunk and version branches )

Forrest Files

Forrest includes these files that you can modify for the Pig website site 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/ – location of the XML doc files
• /src/docs/src/documentation/content/xdocs/site.xml – add or remove *.xml docs files here; controls which documents appear in the doc 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

...

• /src/docs/src/build/site – location of the HTML and PDF docs files (generated when the “forrest” command is run)

Updating the Pig Site Documentation

Checkout the site branch: https://svn.apache.org/repos/asf/pig/site/^{Image Removed}

To edit website doc XML site 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/^{Image Removed} - 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 site 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 output will still be generated; however, be sure to fix any broken links before checking in the files).
• To check the *.html and *.pdf output, move to this output directory: /site/author/build/site

To push your changes to Pig's website:

• Once you are happy with the content in /site/author/build/site, copy your changes to publish: cp -pr author/build/site/* publish
• Make sure you svn add any new files under /site/publish
• svn commit your changes
• Your changes should appear on the website within a few minutes

Updating the Pig User Documentation

Checkout the trunk or relevant branch: http://svn.apache.org/repos/asf/pig/trunk^{Image Removed}

To edit the user XML 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, or remove obsolete 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/^{Image Removed} - 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 output will still be generated; however, be sure to fix any broken links before checking in the files).
• 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

For releases, be sure to do the following:

• Update the doc tab
  • Open the tabs.xml file (…/src/docs/src/documentation/content/xdocs/tabs.xml)
  • Update the doc tab for the current release. For example, change <tab label="Pig 0.69.0 Documentation" dir="" type="visible" /> to <tab label="Pig 0.710.0 Documentation" dir="" type="visible" />
• Update the API link
  • Open the site.xml file (…/src/docs/src/documentation/content/xdocs/site.xml)
  • Update the external api reference for the current release. For example, change <api href="http://pig.apache.org/docs/r0.69.0/api/" /> to <api href="http://pig.apache.org/docs/r0.710.0/api/" />
• Update the documentation index (/src/docs/src/documentation/content/xdocs/pig-index.xml)
  • When adding, updating, or deleting Pig features in the XML doc files, be sure to update the pig-index.xml file. The index is an aid to users and enhances the usability of the Pig documentation.