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

When a user views a goal's options by entering ./pants compile -h or browsing the Pants Options Reference, they see text that "lives" in the Pants source code. If you develop a Task, document it:

Goal description: You can explicitly register a goal's description using Goal.register(name, 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 build-support/bin/publish_docs.sh. To see the options available for this script, run:

./build-support/bin/publish_docs.sh -h

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

The -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 dist/docsite.

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 setting the GIT_URL environment variable.

Use the same script as for generating the site, but request it also be published with -p. 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://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

Cross References

If your doc has a link like <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 pantsref, e.g., <a pantsref="bdict_java_library">java_library</a>.

Doc Site Config

The site generator takes "raw" .html files, "wraps" them in a template with some navigation UI, and writes out the resulting .html files.

You configure this with src/docs/docsite.json:

sources:
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 dist/builddict/build_dictionary.html and apply the template to it.

tree:
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.

template:
Path to mustache template to apply to each page.

extras:
Map of "extra" files to copy over. Handy for graphics, stylesheets, and such.

outdir:
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 tree hierarchy.