This directory contains the source files for Buck's HTML documentation, as well as the scripts to publish that documentation.

Editing Documentation

Buck documentation is written using Closure Templates. The documentation can be viewed locally by running the following command:


and then navigating to http://localhost:9811/ in your browser.

The typical edit/refresh style of web development applies for editing these docs: edit a documentation source file, then refresh the corresponding page in your local view of the docs. This edit/refresh workflow is made possible via plovr, which is a build tool for Closure Templates.

Ideally, changes to Buck code will include updates to these docs in the same commit so that the relationship between the code and documentation changes is clear.

Publishing Documentation

This documentation is hosted publicly at using GitHub Pages. Therefore, to publish this documentation, you must commit it on the gh-pages branch of the GitHub repository by running:

# Both build the docs with plovr in the background
# (serving them on TCP port 9814) and push the
# docs to GitHub Pages
cd docs
./ --start-soyweb

Because this script interacts with GitHub, you should have your GitHub credentials configured as described at Generating a new SSH key and adding it to the ssh-agent.


The Javadoc on the Buck website is updated whenever the documentation is published. (See previous section.)

To generate the Javadoc locally, from the root of the Buck tree, build the Javadoc with ant:

ant javadoc-with-android

To view the generated Javadoc, either open


in your browser, or to use the local web server on your computer, copy the Javadoc to the docs directory:

cp -r ant-out/javadoc-with-android/ docs/javadoc/

and view the Javadoc at http://localhost:9811/javadoc.

Creating a New Article

Create a file and seed it with the following content:

{namespace buck.ADD_YOUR_PAGE_NAME}

{template .soyweb}
    {param title: 'ADD_YOUR_TITLE' /}
    {param content}



Update the three placeholders in all caps and you should be good to go!