Updates for documentation followon from Radical site redesign

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

zundel
pants
zundel/doc-updates
3310
1f3fab9...
pants-reviews
benjyw, jsirois, lahosken, molsen, patricklaw, stuhood

Updates to the concepts page, Invoking Pants and the 3rdparty JVM page.

Staged at:
http://pantsbuild.github.io/staging/zundel/first_concepts.html
http://pantsbuild.github.io/invoking.html
http://pantsbuild.github.io/staging/zundel/3rdparty_jvm.html

  • 0
  • 0
  • 7
  • 1
  • 8
Description From Last Updated
  1. 
      
  2. to exist as source in the repo but also be published as a binary to

    ?

  3. Syntax is: rglobs('*.java')

    But also, to line up with 1:1:1, recommend using globs instead.

  4. Previous indentations was correct, afaik.

  5. src/docs/first_concepts.md (Diff revision 1)
     
     
     

    Since you refer to targets in the definition of Task, move the definition of Target before the definition of Task.

    1. I decided to just reword since I documented goals and tasks together.

  6. src/docs/first_concepts.md (Diff revision 1)
     
     
     

    Tasks always belong to a goal, even if it is implicit. The case where a task is installed without a goal name is effectively just shorthand for creating a goal with the same name as the task.

  7. src/docs/first_concepts.md (Diff revision 1)
     
     
     
     

    Linking to the dev docs explanation of product types might be good here.

  8. src/docs/first_concepts.md (Diff revision 1)
     
     

    xx: dependency libraries.

  9. src/docs/first_concepts.md (Diff revision 1)
     
     
     

    Maybe move this to the header of the Target Types section?

  10. src/docs/first_concepts.md (Diff revision 1)
     
     

    Worth mentioning "default" targets/addresses here, where the name of a target matches its directory?

    1. That is documented elsewhere, I added a pointer.

  11. src/docs/first_concepts.md (Diff revision 1)
     
     

    s/toals/goals/

  12. src/docs/first_concepts.md (Diff revision 1)
     
     
     
     

    Hm, this isn't true at the moment: we do test all targets.

    But it probably meant to say something about how tasks fail fast: if you fail to run test.junit, you may not make it to test.pytest

    1. I think the existing doc is OK. It says that compilation fails, not testing.

  13. src/docs/first_concepts.md (Diff revision 1)
     
     
     

    "attempts to apply" is a bit misleading... maybe just "executes", with a reminder that a task chooses whether to care about a target or not.

  14. src/docs/first_concepts.md (Diff revision 1)
     
     

    You switched the apply to goal to apply to task above, so this is mismatched.

  15. src/docs/invoking.md (Diff revision 1)
     
     

    This made more sense before I think.

    1. Do you mean to just add the - back in?

    2. Yea. Because otherwise this could read as (global|fully) qualified flags without an oxford comma.

  16. src/docs/invoking.md (Diff revision 1)
     
     

    s/actually//

    Note that they can't be passed after the --, as then they would be consumed as passthrough args.

  17. src/docs/invoking.md (Diff revision 1)
     
     

    s/although the goal/although the task/

  18. src/docs/invoking.md (Diff revision 1)
     
     
     
     
     
     
     
     
     
     
     
     
     

    The ordering of the examples seem inverted maybe.

    1. ...although this probably flows more clearly when it is rendered, so maybe nevermind.

  19. 
      
  1. 
      
  2. src/docs/first_concepts.md (Diff revision 2)
     
     

    Oh my, this page looks WAY better now. Thanks!!

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

    I guess I forgot to delete this when I made the separate "why use pants" page... Thanks for fixing.

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

    This should probably link to the options page for more detail?

  5. 
      
  1. looks good to me, one small nit.

  2. src/docs/invoking.md (Diff revision 2)
     
     
     
     
     
     
     

    In some places we seem to precede the command with $ and others we don't. I don't really mind which we do but we should probably be consistent.

  3. 
      
Review request changed

Status: Closed (submitted)

Change Summary:

Thanks Benjy, Stu and Matt. If there are more followups I'll submit a new change. 1dd44b0

  1. Ship It!
  2. 
      
Loading...