Skip to end of metadata
Go to start of metadata

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