Add "common tasks" docs

Review Request #4384 — Created Nov. 16, 2016 and submitted

thoward37
pants
lperkins/pants-cookbook-oss
4060
pants-reviews
ity, lahosken, stuhood, zundel

This PR represents work done by @lucperkins prior to leaving Twitter. These docs were originally an internal corpus called the "Pants Cookbook". We'd like to merge these into the open source docs. Luc did the work of preparing these for PR, and asked me to follow up and finish the review process.

About the docs: these represent very simple step-by-step task-based docs which cover a wide range of use cases.

Tested doc build locally using: ./build-support/bin/publish_docs.sh -o

  • 0
  • 0
  • 2
  • 0
  • 2
Description From Last Updated
ST
  1. There is a lot to review here: thanks to you and Luc!

    I've published this to the pantsbuild.org staging site here for people to review: http://www.pantsbuild.org/staging/cookbook-test-site/index.html

    Personally, I'd prefer to commit it and fix forward after a few organizational bits have been figured out. One or two blockers mentioned below though.

  2. Jenkinsfile (Diff revision 1)
     
     

    This was removed in master.

    1. git rm'd to avoid zombieing it.

  3. src/docs/common_tasks/BUILD (Diff revision 1)
     
     
     
     
     

    Note that page targets support declaring links between pages, which are maintained by the build process: see the page target here: http://www.pantsbuild.org/build_dictionary.html .

    In the markdown itself you use syntax like:

    [[this is a link to a page|pants('this/is/the/path/to/the/page:target')]]
    
    1. Sounds cool! Maybe on another another pass through we could refactor to use this kind of cross linking.

  4. src/docs/docsite.json (Diff revision 1)
     
     
     
     

    Could maybe put this up under Pants Basics, rather than in its own section?

    1. Agreed that having a whole section for a single page seems silly. Pants Basics seems to be well structured and somewhat linear. Maybe tacking this onto the end of Getting Started might fit better. I updated to put it there for now.

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

    ditto

    1. Agreed. Moved Thrift task under General section.

  6. 
      
TH
LA
  1. Yay, I like "cookbook" documentation.
    
    Careful: there are some places here where my knowledge is rusty. Would be good if some current Pants user gave this review a skeptical look.
  2. publish-to-university-server.sh (Diff revision 1)
     
     
    I bet this script wants to live in Twitter somewhere, not in the outside world. And maybe that "lperkins" should become something else.
  3. src/docs/common_tasks/clean.md (Diff revision 1)
     
     
    rm this unterminated strin^W sentence?
    
    (If I were more rigorous, I'd do a clean-all to see if it outputs an URL so we could doc what that URL was. But oh gee whiz that's kind of drastic. Does anyone remember what it says?)
    1. I ran a clean-all, and didn't see any sort of URL-like output, so I'm assuming that's just a random bit of copy pasta that wasn't meant to ship. Removed it.

  4. src/docs/common_tasks/cli_args.md (Diff revision 1)
     
     
    I'm an ignorant cuss who doesn't know what it means to "use passthrough". Does it mean "use --"? If so, might be worth tossing in a parenthetical remark to that effect.
    1. Updated wording/usage to be more clear.

  5. src/docs/common_tasks/compile.md (Diff revision 1)
     
     
    nit: "will compile" -> "compiles"
    1. passive voice, boo. active voice, yay!

  6. src/docs/common_tasks/compile.md (Diff revision 1)
     
     
    My memories are hazy but: Is this specific mention of "binaries" warning me that compiling a library is a no-op? And to really compile it, I need to say a binary target? If so, good to mention that.
    
    Would a test target also work for this make-sure-it-compiles purpose? If so, could be worth a mention.
    1. This doc, in general, is a little confusing, IMO. For example, the side-discussion of Python libraries/binaries seems odd in a doc titled "Compile a JVM target". If anything, it could be included as part of the "Discussion" section, but not as part of the "Solution" section. In fact, those two sections seem to want to be swapped. So I did that.

      Also, it seems to make more sense to use the actual example targets in the pants repo here, instead of random fake targets, so I updated that.

      Regarding test targets, while I agree that they are relevant, in that they also perform JVM compilation, it seems like it would be more of a distraction than a help to include a mention here.

  7. src/docs/common_tasks/compile.md (Diff revision 1)
     
     
    nit: "work" -> "works"
  8. src/docs/common_tasks/index.md (Diff revision 1)
     
     
    nit: "solve...tasks" sounds funny.
    
    maybe: "is devoted to helping you solve some of" -> "describes"
    1. Changed. Yay concision!

  9. src/docs/common_tasks/jvm_options.md (Diff revision 1)
     
     
    nit: the JVM options are command-line options.
    
    maybe: "command-line arguments" -> "arguments to your executable" (which unfortunately echoes the name in the link, but I don't have a better idea?)
    1. Maybe

      You need to specify command-line options to the JVM itself when running a Scala or Java goal (Examples of JVM options can be found [...])
      
      If you need to pass command-line arguments to the application running on the JVM, see ....
      
    2. Revised to be more clear about the difference between options passed to JVM vs executable targets (see updated revision).

  10. src/docs/common_tasks/repl.md (Diff revision 1)
     
     
    "If you're project doesn't specify \*any\* external dependencies, you will only be able to" -> "You can only" (I think this is true whether or not my project specifies external deps, so I'd omit that phrase. If I didn't omit it, I'd fix the "you're")
    
    If I understand what this phrase was trying to warn me about maybe it'd be good to tack on another sentence after this one: There's no way to "import" code that your target doesn't depend on.
    1. Agreed. This sentence seems superfluous, so I removed it.

  11. 
      
MA
  1. Not a blocker if there is a rush, but I would also like to try and read this before it lands.

    I will try to dedicate the time tomorrow afternoon. I will certainly be willing to ship as part of this Friday's release if you are ready for that.

  2. 
      
TH
MA
  1. So I think this is a great contribution. Thanks to you and luc for preparing for public release.

    I am doing a release today around 3 or 3 EST. Someone can ping me if you would like me to hold until this lands.

    1. @mateo: The release process publishes the site, but you can also publish the site at any other time. So no need to synchronize them.

  2. src/docs/common_tasks/pex.md (Diff revision 2)
     
     

    a link to Pex docsite or github page would be a good followup, it will be new to most of the audience reading this.

  3. 
      
TH
ST
  1. Ship It!
    1. Awesome! How do I go about getting this merged? I've ensured the Github PR is in sync with the code here, but I don't have write access, so can't just push the change. One of the Pants committers will merge it, I guess?

    2. Hey Troy!

      Sorry for the delay... I just went to merge this, but it looks like Travis is red for your most recent build: https://travis-ci.org/pantsbuild/pants/builds/178194763 you should be able to repro by trying to rebuild the site locally.

      As soon as that is fixed we can merge.

    3. Oops! Looks like I failed to include the new .md files in my last commit, which is what was breaking the build. Added those.

  2. 
      
TH
TH
Review request changed

Status: Closed (submitted)

Change Summary:

Merged as 4426613510c9cd02609b69709db7abc797a4dc37

Loading...