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().register_options(register) register('--libraries', default=True, type=bool, help='Causes libraries to be output.')
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
The site is generated with a script at
see the options available for this script, run:
To see http://www.pantsbuild.org/ site's content as it would be generated based on your local copy of the pants repo, enter the command:
# This generates the site html in dist/docsite and opens (-o) index.html in your browser for review. ./build-support/bin/publish_docs.sh -o
-l <dir> option will copy the site over to the existing local directory
<dir> after generation, which can be used to publish the site into a non-git
repo, for example. If this option is specified along with
-o, the script will
open the version of the site in
<dir> instead of in
Publishing the site
We publish the site via Github Pages. You need
pantsbuild commit privilege to publish to the site at
https://www.pantsbuild.org, but you can also publish to any repo you own by
GIT_URL environment variable.
Use the same script as for generating the site, but request it also be published
-p. Don't worry—you'll get a chance to abort the publish just before it's
# 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://www.pantsbuild.org ./build-support/bin/publish_docs.sh -op
If you'd like to test remote publishing or preview an alternate version of the
site without modifying the main site, the
-d option creates a copy of the site
in a subdir of the
VIEW_PUBLISH_URL environment variable. This variable defaults to
https://www.pantsbuild.org/, but publishing to the main site requires
pantsbuild commit privilege.
# 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://www.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