Merge back in some content from the options page

Review Request #3795 — Created April 30, 2016 and submitted

zundel
pants
zundel/doc-updates2
d315a22...
pants-reviews
benjyw, jsirois, molsen, patricklaw, stuhood

This re-instantes some content from the old 'invoking' page and put it in the 'options' page.
Also fixes a heading and moves some sections around.

See comments in https://rbcommons.com/s/twitter/r/3767

Staged at http://pantsbuild.github.io/staging/zundel2/options.html

  • 0
  • 0
  • 3
  • 1
  • 4
Description From Last Updated
  1. 
      
  2. src/docs/options.md (Diff revision 1)
     
     

    This section isn't changed, I just moved it up so I could put all the stuff about config files together at the bottom

  3. src/docs/options.md (Diff revision 1)
     
     

    I reversed the order, again so I could put all of the config file stuff together at the end

  4. 
      
  1. 
      
  2. src/docs/options.md (Diff revision 1)
     
     

    Boolean flag values

  3. src/docs/options.md (Diff revision 1)
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     

    Now that verify-config is enabled by default, this section can probably be dropped entirely.

    1. I think this still has value. Verify config just tells you that you did something wrong, not why or how to find out what the right way to do it is.

  4. src/docs/options.md (Diff revision 1)
     
     
     
     
     
     

    Maybe worth moving the PEP reference from
    https://pantsbuild.github.io/install.html#recommended-installation

    ...to here, and then linking from there to here?

  5. 
      
  1. 
      
  2. src/docs/options.md (Diff revision 2)
     
     

    I want to deprecate --config-override, so I'd rather not mention it here. Instead, people should use --pants-config-files, which is list-valued, so you can both append and replace it, which is far more flexible than --config-override, which is effectively like a single append.

    1. OK, I'll update it. Note that --pants-config-files doesn't change the values in the help text, so I can't verify what values are actually being set. The help text doesn't fold in any over the values from the overridden config files. Presumably that is fixable. I filed an issue https://github.com/pantsbuild/pants/issues/3313

  3. src/docs/options.md (Diff revision 2)
     
     

    This seems unnecessarily vague. We introduce the concept of scopes above, and we explain that section names are scope names.

    It's fine to point out this gotcha here, but the emphasis should be on knowing the scope of your option. Talking about "arbitrarily stripping off the first part of the option name" and "section names can have multiple parts" seems like a step away from that specificity.

  4. src/docs/options.md (Diff revision 2)
     
     

    Again, this should reference the concept of scopes. Section names aren't some independent concept.

  5. 
      
  1. 
      
  2. src/docs/options.md (Diff revision 2)
     
     
     

    In the past we seem to have used advanced to denote options that generally people shouldn't be changing. Should we be making it so visible in our documentation?

    Maybe we should put a warning about using advanced options.

    1. This page is for end users and administrators. Administrators need documentation too! The preceeding paragaph seems to cover the caveat that advanced options are only for administrators?

    2. I added a bit more verbage around the idea though and explained a more of the 'why' for the decision not to expose advanced options.

  3. 
      
  1. 
      
  2. src/docs/options.md (Diff revision 3)
     
     

    Maybe mention that this is a list-valued option, so all the idioms of lists work: E.g., you can add a third file with another invocation of --pants-config-files=path, or you can replace the standard one entirely with --pants-config-files=[<list>].

  3. 
      
Review request changed

Status: Closed (submitted)

Change Summary:

Thanks Stu, Benjy, Matt. Commit add4304

Loading...