Forrest Set Up

Pig's official documentation is authored using Forrest. To commit documentation changes you must have Forrest installed and the Forrest executable 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 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 – controls which documents appear in the doc menu
  • /src/docs/src/documentation/content/xdocs/tabs.xml – controls which tabs appear on each page
  • /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/

To edit 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:

  • 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 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 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: /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

To edit the XML doc files:

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

To view your edits:

  • Change to the directory that includes the forrest.properties file: /trunk/src/docs
  • 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 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 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

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.9.0 Documentation" dir="" type="visible" /> to <tab label="Pig 0.10.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.9.0/api/" /> to <api href="http://pig.apache.org/docs/r0.10.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.
  • No labels