Versions Compared

Old Version 1

changes.mady.by.user Daniel Dai

Saved on

compared with

New Version 2

changes.mady.by.user Corinne Chandel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor updates here and there ....

...

Pig's official documentation is authored using Forrest. To commit documentation changes you must have Forrest installed and the forrest Forrest executable on in 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 Pig site documentation (maintained separately in subversion, in the site branch)
  1. The Pig user documentation , versioned with releases (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/

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

...

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

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/ - 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.