Merge pull request Yelp#618 from irskep/clarify-mrjob-cmd-docs

Clarify purpose of mrjob.cmd in 0.4
tarnfeld · Mar 25, 2013 · 8e0a00f · 8e0a00f
2 parents 12c7674 + 387e1ce
commit 8e0a00f
Show file tree

Hide file tree

Showing 10 changed files with 29 additions and 7 deletions.
diff --git a/docs/guides/cmd.rst b/docs/guides/cmd.rst
@@ -3,13 +3,14 @@
 The ``mrjob`` command
 =====================
 
-You can use the ``mrjob`` command to run jobs written in any language or
-perform various Elastic MapReduce-related tasks.
+The ``mrjob`` command has two purposes:
 
-``mrjob run (path to script or executable) [options]``
-    Run a job. Takes same options as invoking a Python job. See
-    :doc:`configs-all-runners`, :doc:`configs-hadoopy-runners`, and
-    :doc:`emr-opts`.
+1. To provide easy access to EMR tools
+2. To eventually let you run Hadoop Streaming jobs written in languages other
+   than Python
+
+EMR tools
+---------
 
 ``mrjob audit-emr-usage [options]``
     Audit EMR usage over the past 2 weeks, sorted by job flow name and user.
@@ -50,3 +51,12 @@ perform various Elastic MapReduce-related tasks.
     Terminate an existing EMR job flow.
 
     Alias for :py:mod:`mrjob.tools.emr.terminate_job_flow`.
+
+Running jobs
+------------
+
+``mrjob run (path to script or executable) [options]``
+    Run a job. Takes same options as invoking a Python job. See
+    :doc:`configs-all-runners`, :doc:`configs-hadoopy-runners`, and
+    :doc:`emr-opts`. While you can use this command to invoke your jobs, you
+    can just as easily call ``python my_job.py [options]``.
diff --git a/docs/guides/emr-tools.rst b/docs/guides/emr-tools.rst
@@ -1,6 +1,9 @@
 EMR job flow management tools
 =============================
 
+Each tool can be invoked two ways: from the ``mrjob`` command, or by running
+the Python module directly. Both ways are given in each example.
+
 audit_usage
 -----------
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -36,7 +36,6 @@ Guides
 
 * :doc:`guides/runners`
 * :ref:`runners-programmatically`
-* :doc:`guides/cmd`
 * :doc:`guides/testing`
 
 **Configuration**
@@ -60,6 +59,7 @@ Guides
 * :ref:`picking-job-flow-config`
 * :doc:`guides/emr-opts`
 * :doc:`guides/emr-tools`
+* :doc:`guides/cmd`
 * :doc:`guides/emr-troubleshooting`
 * :doc:`guides/emr-advanced`
 

diff --git a/mrjob/tools/emr/audit_usage.py b/mrjob/tools/emr/audit_usage.py
@@ -15,6 +15,7 @@
 
 Usage::
 
+    mrjob audit-emr-usage > report
     python -m mrjob.tools.emr.audit_usage > report
 
 Options::

diff --git a/mrjob/tools/emr/create_job_flow.py b/mrjob/tools/emr/create_job_flow.py
@@ -16,6 +16,7 @@
 
 Usage::
 
+    mrjob create-job-flow
     python -m mrjob.tools.emr.create_job_flow
 
 **WARNING**: do not run this without having

diff --git a/mrjob/tools/emr/fetch_logs.py b/mrjob/tools/emr/fetch_logs.py
@@ -17,6 +17,8 @@
 
 Usage::
 
+    mrjob fetch-logs -[l|L|a|A|--counters] [-s STEP_NUM]\
+ JOB_FLOW_ID
     python -m mrjob.tools.emr.fetch_logs -[l|L|a|A|--counters] [-s STEP_NUM]\
  JOB_FLOW_ID
 

diff --git a/mrjob/tools/emr/report_long_jobs.py b/mrjob/tools/emr/report_long_jobs.py
@@ -16,6 +16,7 @@
 
 Suggested usage: run this as a daily cron job with the ``-q`` option::
 
+    0 0 * * * mrjob report-long-jobs
     0 0 * * * python -m mrjob.tools.emr.report_long_jobs -q
 
 Options::

diff --git a/mrjob/tools/emr/s3_tmpwatch.py b/mrjob/tools/emr/s3_tmpwatch.py
@@ -19,11 +19,13 @@
 
 Suggested usage: run this as a cron job with the -q option::
 
+    0 0 * * * mrjob s3-tmpwatch -q 30d s3://your-bucket/tmp/
     0 0 * * * python -m mrjob.tools.emr.s3_tmpwatch -q 30d \
 s3://your-bucket/tmp/
 
 Usage::
 
+    mrjob s3-tmpwatch [options] <time-untouched> <URIs>
     python -m mrjob.tools.emr.s3_tmpwatch [options] <time-untouched> <URIs>
 
 Options::

diff --git a/mrjob/tools/emr/terminate_idle_job_flows.py b/mrjob/tools/emr/terminate_idle_job_flows.py
@@ -17,6 +17,7 @@
 
 Suggested usage: run this as a cron job with the ``-q`` option::
 
+    */30 * * * * mrjob terminate-idle-job-flows -q
     */30 * * * * python -m mrjob.tools.emr.terminate_idle_job_flows -q
 
 Options::

diff --git a/mrjob/tools/emr/terminate_job_flow.py b/mrjob/tools/emr/terminate_job_flow.py
@@ -15,6 +15,7 @@
 
 Usage::
 
+    mrjob terminate-job-flow [options] j-JOBFLOWID
     python -m mrjob.tools.emr.terminate_job_flow [options] j-JOBFLOWID
 
 Terminate an existing EMR job flow.