tree: ba3b30d16dd27b13be0956d00d2ed7c2a4f2fee3 [path history] [tgz]
  1. .nojekyll
  2. BUCK
  3. README.md
  4. __android_common.soy
  5. __apple_common.soy
  6. __buckconfig_common.soy
  7. __command_common.soy
  8. __common.soy
  9. __cxx_common.soy
  10. __d_common.soy
  11. __genrule_common.soy
  12. __go_common.soy
  13. __haskell_common.soy
  14. __jvm_common.soy
  15. __lua_common.soy
  16. __native_common.soy
  17. __navigation.soy
  18. __ocaml_common.soy
  19. __python_common.soy
  20. __remote_common.soy
  21. __rust_common.soy
  22. __table_of_contents.soy
  23. __test_common.soy
  24. about/
  25. alphabetize_buckconfig.py
  26. article/
  27. buckconfig_aliases_clean.py
  28. command/
  29. concept/
  30. extending/
  31. files-and-dirs/
  32. function/
  33. generate_buckconfig_aliases.py
  34. globals.json
  35. google-code-prettify/
  36. index.soy
  37. learning/
  38. plovr-81ed862.jar
  39. presentations/
  40. publish.sh
  41. rule/
  42. setup/
  43. skylark/
  44. soy2html.py
  45. soy2html.sh
  46. soy_syntax_check.py
  47. soyweb-local.ps1
  48. soyweb-local.sh
  49. soyweb-prod.sh
  50. static/
docs/README.md

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:

./docs/soyweb-local.sh

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 http://facebook.github.com/buck/ 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
./publish.sh --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.

Javadoc

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

ant-out/javadoc-with-android/index.html 

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}
  {call buck.page}
    {param title: 'ADD_YOUR_TITLE' /}
    {param content}

ADD_YOUR_CONTENT_HERE

    {/param}
  {/call}
{/template}

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