Re: Review Request 4384: Add "common tasks" docs

[Stu Hood]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

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.

Jenkinsfile (Diff revision 1)
		8

This was removed in master.

publish-to-university-server.sh (Diff revision 1)
		4

xx

src/docs/common_tasks/BUILD (Diff revision 1)
		96	page(
		97	name='server',
		98	source='server.md',
		99	)

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')]]

src/docs/docsite.json (Diff revision 1)
98		125
		126	{ "heading": "Cookbook" },
		127	{ "page": "common_tasks" },

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

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

ditto

- Stu Hood

On November 16th, 2016, 8:28 p.m. UTC, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul and Stu Hood. By Troy Howard. Updated Nov. 16, 2016, 8:28 p.m. Bugs: 4060 Repository: pants Description 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. Testing Tested doc build locally using: ./build-support/bin/publish_docs.sh -o Diffs Jenkinsfile (PRE-CREATION) publish-to-university-server.sh (PRE-CREATION) src/README.md (1281868bb0197a65868e03111d44354ca3c9c837) src/docs/BUILD (cddf85e8979230068df537107af62227fa8a38be) src/docs/common_tasks/BUILD (PRE-CREATION) src/docs/common_tasks/bundle.md (PRE-CREATION) src/docs/common_tasks/clean.md (PRE-CREATION) src/docs/common_tasks/cli_args.md (PRE-CREATION) src/docs/common_tasks/compile.md (PRE-CREATION) src/docs/common_tasks/file_bundles.md (PRE-CREATION) src/docs/common_tasks/globs.md (PRE-CREATION) src/docs/common_tasks/index.md (PRE-CREATION) src/docs/common_tasks/jvm_binary.md (PRE-CREATION) src/docs/common_tasks/jvm_library.md (PRE-CREATION) src/docs/common_tasks/jvm_options.md (PRE-CREATION) src/docs/common_tasks/jvm_tests.md (PRE-CREATION) src/docs/common_tasks/list_goals.md (PRE-CREATION) src/docs/common_tasks/list_targets.md (PRE-CREATION) src/docs/common_tasks/pex.md (PRE-CREATION) src/docs/common_tasks/python_library.md (PRE-CREATION) src/docs/common_tasks/python_tests.md (PRE-CREATION) src/docs/common_tasks/repl.md (PRE-CREATION) src/docs/common_tasks/resources.md (PRE-CREATION) src/docs/common_tasks/run.md (PRE-CREATION) src/docs/common_tasks/server.md (PRE-CREATION) src/docs/common_tasks/test.md (PRE-CREATION) src/docs/common_tasks/test_suite.md (PRE-CREATION) src/docs/common_tasks/thrift_gen.md (PRE-CREATION) src/docs/docsite.json (c32357f849e18e6412ff069266b8345da979147c) src/docs/images/pants-server-ui.png (PRE-CREATION) src/docs/index.md (4ac382c5d178b0b3c713037b2b86eff17b813607) View Diff

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

Review request for pants-reviews, Ity Kaul and Stu Hood. By Troy Howard.

[Larry Hosken]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

Fix it, then Ship it!

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.

publish-to-university-server.sh (Diff revision 1)
		6	rsync -azh dist/docsite/* lper...@university.twitter.biz:~/public_html/pants

I bet this script wants to live in Twitter somewhere, not in the outside world. And maybe that "lperkins" should become something else.

src/docs/common_tasks/clean.md (Diff revision 1)
		14	In the output, you'll find a URL for

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?)

src/docs/common_tasks/cli_args.md (Diff revision 1)
		9	With Pants, you can use passthrough to pass arguments directly to the process that you're executing:

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.

src/docs/common_tasks/compile.md (Diff revision 1)
		5	You need to compile a library target that you're currently working on, e.g. if you want to ensure that the target will compile successfully.

nit: "will compile" -> "compiles"

src/docs/common_tasks/compile.md (Diff revision 1)
		9	The `compile` goal enables you to compile Scala or Java [[binaries|]]. Here's an example:

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.

src/docs/common_tasks/compile.md (Diff revision 1)
		14	This work somewhat differently if you're working on `python_library` targets because these targets never require a separate compilation phase, even when you're using the library locally. You can, however, compile Python binary targets. See [[Build a Python Executable|pants('src/docs/common_tasks:pex')]] and [[Run a Binary Target|pants('src/docs/common_tasks:run')]] for more info.

nit: "work" -> "works"

src/docs/common_tasks/index.md (Diff revision 1)
		3	This section of the Pants documentation is devoted to helping you solve some of

nit: "solve...tasks" sounds funny.

maybe: "is devoted to helping you solve some of" -> "describes"

src/docs/common_tasks/jvm_options.md (Diff revision 1)
		7	If you need to pass command-line arguments instead, see [[Pass Command-line Arguments to an Executable|pants('src/docs/common_tasks:cli_args')]].

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?)

src/docs/common_tasks/repl.md (Diff revision 1)
		26	If you're project doesn't specify *any* external dependencies, you will only be able to interact with the classes, functions, etc. that are available from the runtime you're working with.

"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.

- Larry Hosken

On November 16th, 2016, 1:02 p.m. PST, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard. Updated Nov. 16, 2016, 1:02 p.m.

[Mateo Rodriguez]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

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.

- Mateo Rodriguez

On November 16th, 2016, 3:02 p.m. CST, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 16, 2016, 3:02 p.m.

[Nick Howard (Twitter)]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

On November 16th, 2016, 3:32 p.m. MST, Larry Hosken wrote:

src/docs/common_tasks/jvm_options.md (Diff revision 1)
		7	If you need to pass command-line arguments instead, see [[Pass Command-line Arguments to an Executable|pants('src/docs/common_tasks:cli_args')]].

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?)

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 ....

- Nick

On November 16th, 2016, 2:02 p.m. MST, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 16, 2016, 2:02 p.m.

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 18, 2016, 10:16 a.m. Changes Responded to review feedback. Includes minor wording and IA changes.

Bugs: 4060 Repository: pants Description 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. Testing Tested doc build locally using: ./build-support/bin/publish_docs.sh -o

Diffs (updated)

Show Changes

[Mateo Rodriguez]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

Ship it!

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.

src/docs/common_tasks/pex.md (Diff revision 2)
		5	You need to create an executable `.pex` Python binary (aka a "PEX") out of Python source code.

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

- Mateo Rodriguez

On November 18th, 2016, 4:16 a.m. CST, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 18, 2016, 4:16 a.m.

Bugs: 4060 Repository: pants Description 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. Testing Tested doc build locally using: ./build-support/bin/publish_docs.sh -o Diffs

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

On November 18th, 2016, 3:56 p.m. UTC, Mateo Rodriguez wrote:

src/docs/common_tasks/pex.md (Diff revision 2)
		5	You need to create an executable `.pex` Python binary (aka a "PEX") out of Python source code.

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

Added a link!

- Troy

On November 18th, 2016, 6:12 p.m. UTC, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 18, 2016, 6:12 p.m.

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

On November 16th, 2016, 9 p.m. UTC, Stu Hood wrote:

Jenkinsfile (Diff revision 1)
		8

This was removed in master.

git rm'd to avoid zombieing it.

On November 16th, 2016, 9 p.m. UTC, Stu Hood wrote:

publish-to-university-server.sh (Diff revision 1)
		4

xx

Derp. rm'd

On November 16th, 2016, 9 p.m. UTC, Stu Hood wrote:

src/docs/common_tasks/BUILD (Diff revision 1)
		96	page(
		97	name='server',
		98	source='server.md',
		99	)

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')]]

Sounds cool! Maybe on another another pass through we could refactor to use this kind of cross linking.

On November 16th, 2016, 9 p.m. UTC, Stu Hood wrote:

src/docs/docsite.json (Diff revision 1)
98		125
		126	{ "heading": "Cookbook" },
		127	{ "page": "common_tasks" },

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

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.

On November 16th, 2016, 9 p.m. UTC, Stu Hood wrote:

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

ditto

Agreed. Moved Thrift task under General section.

- Troy

On November 18th, 2016, 6:12 p.m. UTC, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers.

By Troy Howard. Updated Nov. 18, 2016, 6:12 p.m.

Bugs: 4060 Repository: pants Description 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. Testing Tested doc build locally using: ./build-support/bin/publish_docs.sh -o Diffs

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 18, 2016, 6:12 p.m. Changes I noticed a bunch of TODOs, so I fixed those! That meant adding two new tasks (alias/dependencies), which need review. Also included updates per review feedback.

[Stu Hood]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

On November 18th, 2016, 3:56 p.m. UTC, Mateo Rodriguez wrote:

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.

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

- Stu

On November 18th, 2016, 6:12 p.m. UTC, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 18, 2016, 6:12 p.m.

[Stu Hood]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

Ship it!

Ship It!

- Stu Hood

On November 18th, 2016, 6:12 p.m. UTC, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard. Updated Nov. 18, 2016, 6:12 p.m.

Bugs: 4060

Repository: pants Description 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. Testing Tested doc build locally using: ./build-support/bin/publish_docs.sh -o Diffs

[Stu Hood]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

On November 18th, 2016, 10:11 p.m. UTC, Stu Hood wrote:

Ship It!

On November 23rd, 2016, 5:42 a.m. UTC, Troy Howard wrote:

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?

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.

- Stu

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 28, 2016, 7:37 p.m. Changes Add articles for aliases and dependencies.

Bugs: 4060 Repository: pants Description 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. Testing Tested doc build locally using: ./build-support/bin/publish_docs.sh -o Diffs (updated)

src/README.md (1281868bb0197a65868e03111d44354ca3c9c837) src/docs/BUILD (cddf85e8979230068df537107af62227fa8a38be) src/docs/common_tasks/BUILD (PRE-CREATION)

src/docs/common_tasks/alias.md (PRE-CREATION)

src/docs/common_tasks/bundle.md (PRE-CREATION) src/docs/common_tasks/clean.md (PRE-CREATION) src/docs/common_tasks/cli_args.md (PRE-CREATION) src/docs/common_tasks/compile.md (PRE-CREATION)

src/docs/common_tasks/dependencies.md (PRE-CREATION)

src/docs/common_tasks/file_bundles.md (PRE-CREATION) src/docs/common_tasks/globs.md (PRE-CREATION) src/docs/common_tasks/index.md (PRE-CREATION) src/docs/common_tasks/jvm_binary.md (PRE-CREATION) src/docs/common_tasks/jvm_library.md (PRE-CREATION) src/docs/common_tasks/jvm_options.md (PRE-CREATION) src/docs/common_tasks/jvm_tests.md (PRE-CREATION) src/docs/common_tasks/list_goals.md (PRE-CREATION) src/docs/common_tasks/list_targets.md (PRE-CREATION) src/docs/common_tasks/pex.md (PRE-CREATION) src/docs/common_tasks/python_library.md (PRE-CREATION) src/docs/common_tasks/python_tests.md (PRE-CREATION) src/docs/common_tasks/repl.md (PRE-CREATION) src/docs/common_tasks/resources.md (PRE-CREATION) src/docs/common_tasks/run.md (PRE-CREATION) src/docs/common_tasks/server.md (PRE-CREATION) src/docs/common_tasks/test.md (PRE-CREATION) src/docs/common_tasks/test_suite.md (PRE-CREATION) src/docs/common_tasks/thrift_gen.md (PRE-CREATION) src/docs/docsite.json (c32357f849e18e6412ff069266b8345da979147c) src/docs/images/pants-server-ui.png (PRE-CREATION) src/docs/index.md (4ac382c5d178b0b3c713037b2b86eff17b813607)

View Diff Show Changes

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

On November 18th, 2016, 10:11 p.m. UTC, Stu Hood wrote:

Ship It!

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?

- Troy

[Troy Howard]

This is an automatically generated e-mail. To reply, visit: https://rbcommons.com/s/twitter/r/4384/

On November 18th, 2016, 10:11 p.m. UTC, Stu Hood wrote:

Ship It!

On November 23rd, 2016, 5:42 a.m. UTC, Troy Howard wrote:

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?

On November 25th, 2016, 7:49 p.m. UTC, Stu Hood wrote:

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.

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

- Troy

On November 28th, 2016, 7:37 p.m. UTC, Troy Howard wrote:

Review request for pants-reviews, Ity Kaul, Larry Hosken, Stu Hood, and Eric Ayers. By Troy Howard.

Updated Nov. 28, 2016, 7:37 p.m.

Bugs: 4060 Repository: pants Description 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. Testing Tested doc build locally using: ./build-support/bin/publish_docs.sh -o Diffs

src/README.md (1281868bb0197a65868e03111d44354ca3c9c837) src/docs/BUILD (cddf85e8979230068df537107af62227fa8a38be) src/docs/common_tasks/BUILD (PRE-CREATION)

src/docs/common_tasks/alias.md (PRE-CREATION)

src/docs/common_tasks/bundle.md (PRE-CREATION) src/docs/common_tasks/clean.md (PRE-CREATION) src/docs/common_tasks/cli_args.md (PRE-CREATION) src/docs/common_tasks/compile.md (PRE-CREATION)

src/docs/common_tasks/dependencies.md (PRE-CREATION)

src/docs/common_tasks/file_bundles.md (PRE-CREATION) src/docs/common_tasks/globs.md (PRE-CREATION) src/docs/common_tasks/index.md (PRE-CREATION) src/docs/common_tasks/jvm_binary.md (PRE-CREATION) src/docs/common_tasks/jvm_library.md (PRE-CREATION) src/docs/common_tasks/jvm_options.md (PRE-CREATION) src/docs/common_tasks/jvm_tests.md (PRE-CREATION) src/docs/common_tasks/list_goals.md (PRE-CREATION) src/docs/common_tasks/list_targets.md (PRE-CREATION) src/docs/common_tasks/pex.md (PRE-CREATION) src/docs/common_tasks/python_library.md (PRE-CREATION) src/docs/common_tasks/python_tests.md (PRE-CREATION) src/docs/common_tasks/repl.md (PRE-CREATION) src/docs/common_tasks/resources.md (PRE-CREATION) src/docs/common_tasks/run.md (PRE-CREATION) src/docs/common_tasks/server.md (PRE-CREATION) src/docs/common_tasks/test.md (PRE-CREATION) src/docs/common_tasks/test_suite.md (PRE-CREATION) src/docs/common_tasks/thrift_gen.md (PRE-CREATION) src/docs/docsite.json (c32357f849e18e6412ff069266b8345da979147c) src/docs/images/pants-server-ui.png (PRE-CREATION) src/docs/index.md (4ac382c5d178b0b3c713037b2b86eff17b813607)

View Diff