About the documentation
Pants' user-facing documentation lives in markdown sources, in docstrings, and in some other special strings. We keep documentation close to the code it describes. If you change some code and wonder "should I update the docs?" the documentation that needs updating should be nearby.
Docs in the Code
"Reference" information tends to live in the code. (Information for Pants developers, of course, lives in docstrings and comments; but some information for Pants users lives in the code, too.)
Goals, tasks, and options
Goal description: You can explicitly register a goal's description
This description will default to the description of a task in that goal with the same name as the goal, if any.
Task description: Task descriptions are derived from the first sentence of the docstring of the task class.
Option help When registering a
Task option, pass a
help parameter to describe that option.
def register_options(cls, register): super(ListGoals, cls).register_options(register) register('--graph', type=bool, help='Generate a graphviz graph of installed goals.')
Target types and other
BUILD file symbols
When a user views a target's parameters by entering
./pants targets --details=java_library or
by browsing the Pants BUILD Dictionary, that information
is derived from the docstrings of the classes implementing those symbols.
Generating the site
To see http://pantsbuild.org/ site's content as it would be generated based on your local copy of the pants repo, enter the command
# This publishes the docs **locally** and opens (-o) them in your browser for review ./build-support/bin/publish_docs.sh -o
Publishing the site
We publish the site via Github Pages. You need
privilege to publish the site.
Use the same script as for generating the site, but request it also be published. Don't worry—you'll get a chance to abort the publish just before it's committed remotely:
# This publishes the docs locally and opens (-o) them in your browser for review # and then prompts you to confirm you want to publish these docs remotely before # proceeding to publish to http://pantsbuild.org ./build-support/bin/publish_docs.sh -op
If you'd like to publish remotely for others to preview your changes easily, the
-d option creates
a copy of the site in a subdir of http://pantsbuild.org/:
# This publishes the docs locally and opens (-o) them in your browser for review # and then prompts you to confirm you want to publish these docs remotely before # proceeding to publish to http://pantsbuild.org/sirois-test-site ./build-support/bin/publish_docs.sh -opd sirois-test-site
If your doc has a
<a pantsref="bdict_java_library">java_library</a>, it links to
the BUILD Dictionary entry for
java_library. To set up a short-hand
link like this...
Define the destination of the link with an
pantsmark anchor, e.g.,
<a pantsmark="bdict_java_library"> </a>. The
pantsmark attribute (here,
bdict_java_library) must be unique within the doc set.
Link to the destination with an
Doc Site Config
The site generator
.html files, "wraps" them in a template with some
navigation UI, and writes out the resulting
You configure this with
Map of pages to the
.html files they're generated from. E.g.,
"build_dictionary": "dist/builddict/build_dictionary.html", means to
generate the site's /build_dictionary.html page, the site generator
should get the "raw" file
apply the template to it.
Outline structure of the site. Each node of the tree is a dict. Each node-dict can have a
page, a page defined in
sources above. Each
node-dict can have a
children, a list of more nodes.
Path to mustache template to apply to each page.
Map of "extra" files to copy over. Handy for graphics, stylesheets, and such.
Path to which to write the generated site.
To add a page and have it show up in the side navigation UI, add the
page to the
sources dict and to the