Updates for documentation followon from Radical site redesign

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

Eric Ayers
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
Eric Ayers
Stu Hood
  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. 
      
Eric Ayers
Benjy Weinberger
  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. 
      
Matt Olsen
  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. 
      
Eric Ayers
Eric Ayers
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

Larry Hosken
  1. Ship It!
  2. 
      
Loading...