Document pants.ini configuration options.

Review Request #183 — Created April 8, 2014 and submitted

benjyw, lahosken
Mostly a repost of post move to pantsbuild.

Add a simple system to register pants.ini options so we can generate a configuration reference page on our website. Lots of required, undocumented keys in pants.ini has been identified as an issue for new users and this change lays the groundwork. Once the pattern has been defined I'll move all options over to this style in a few future reviews.

Similar to command-line flags, pants developers explicitly define options rather than fetching keys from the config directly. We register these keys enabling the generation of a docs site. A few examples are provided here, and we'll do the rest after reaching consensus on the format. The goal is generating documentation for our users, so we explicitly avoid going overboard and rewriting the whole config system (e.g.: unifying pants.ini & command-line flags which is out of scope for this change).

Eliminate two options that are not obviosuly desiarable to allow users to tweak. In 67 we agreed to remove these rather than document as tuneable: tasks.build_invalidator, reporting.reports_dir

  2. Maybe this should be "pants.ini Configuration Reference"
    I notice some folks calling some thingies "config" that don't live in pants.ini. So I suspect the extra qualifier (which _kind_ of config?) would disambiguate
Review request changed

Status: Closed (submitted)