Update the man page, and in the process, organize cmdline.py

1 files changed, 93 insertions, 14 deletions

diff --git a/doc/python-coverage.1.txt b/doc/python-coverage.1.txt
index 1a06bf2e..27ab1924 100644
--- a/doc/python-coverage.1.txt
+++ b/doc/python-coverage.1.txt
@@ -8,7 +8,7 @@ measure code coverage of Python program execution
 
 :Author: Ned Batchelder <ned@nedbatchelder.com>
 :Author: |author|
-:Date: 2019-06-11
+:Date: 2019-11-11
 :Copyright: Apache 2.0 license, attribution and disclaimer required.
 :Manual section: 1
 :Manual group: Coverage.py
@@ -52,6 +52,9 @@ COMMAND OVERVIEW
 |command| **html**
     Create an HTML report.
 
+|command| **json**
+    Create a JSON report of coverage results.
+
 |command| **report**
     Report coverage stats on modules.
 
@@ -69,15 +72,8 @@ GLOBAL OPTIONS
     Describe how to use coverage.py, in general or a command.
 
 **--rcfile** `RCFILE`
-    Specify configuration file `RCFILE`. Defaults to ``.coveragerc``.
-
-**--omit** `PATTERN` [ , ... ]
-    Omit files when their file name matches one of these PATTERNs.
-    Usually needs quoting on the command line.
-
-**--include** `PATTERN` [ , ... ]
-    Include only files whose paths match one of these
-    PATTERNs. Accepts shell-style wildcards, which must be quoted.
+    Specify configuration file `RCFILE`.  By default '.coveragerc',
+    'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
 
 **--debug** `DEBUGOPT`,...
     Debug options `DEBUGOPT`, separated by commas.
@@ -97,6 +93,14 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
 **combine** [ `option` ... ] [ `PATH` ... ]
 
     Combine data from multiple coverage files collected with ``run -p``.
@@ -128,8 +132,8 @@ COMMAND REFERENCE
 
     Options:
 
-    \--contexts `PAT,...`
-        Only include contexts that match one of the patterns.
+    \--contexts `PAT` [ , ... ]
+        Only include contexts that match one of the regex patterns.
 
     \-d `DIR`, --directory `DIR`
         Write the output files to `DIR`.
@@ -140,23 +144,65 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \--show-contexts
         Annotate lines with the contexts that executed them.
 
     \--skip-covered
         Skip files with 100% coverage.
 
+    \--skip-empty
+        Skip files with no code.
+
     \--title `TITLE`
         Use the text string `TITLE` as the title on the HTML.
 
+**json** [ `option` ... ] [ `MODULE` ... ]
+
+    Generate a JSON report of coverage results.
+
+    \--contexts `PAT` [ , ... ]
+        Only include contexts that match one of the regex patterns.
+
+    \--fail-under `MIN`
+        Exit with a status of 2 if the total coverage is less than `MIN`.
+
+    \-i, --ignore-errors
+        Ignore errors while reading source files.
+
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \-o `OUTFILE`
+        Write the JSON report to `OUTFILE`. Defaults to ``coverage.json``.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
+    \--pretty-print
+        Format the JSON for human readers.
+
+    \--show-contexts
+        Include information about the contexts that executed each line.
+
+
 **report** [ `option` ... ] [ `MODULE` ... ]
 
     Report coverage statistics on each `MODULE`.
 
     Options:
 
-    \--contexts `PAT,...`
-        Only include contexts that match one of the patterns.
+    \--contexts `PAT` [ , ... ]
+        Only include contexts that match one of the regex patterns.
 
     \--fail-under `MIN`
         Exit with a status of 2 if the total coverage is less than `MIN`.
@@ -164,6 +210,14 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \-m, --show-missing
         Show line numbers of statements in each module that weren't
         executed.
@@ -171,6 +225,9 @@ COMMAND REFERENCE
     \--skip-covered
         Skip files with 100% coverage.
 
+    \--skip-empty
+        Skip files with no code.
+
 **run** [ `options` ... ] `PROGRAMFILE` [ `program_options` ]
 
     Run a Python program `PROGRAMFILE`, measuring code execution.
@@ -188,6 +245,20 @@ COMMAND REFERENCE
         Properly measure code using a concurrency library. Valid values are:
         thread, gevent, greenlet, eventlet, multiprocessing.
 
+    \--context `CONTEXT`
+        The context label to record for this coverage run.
+
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \-m
+        `PROGRAMFILE` is interpreted as a module name.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \-L, --pylib
         Measure coverage even inside the Python installed library, which
         isn't done by default.
@@ -216,6 +287,14 @@ COMMAND REFERENCE
     \-i, --ignore-errors
         Ignore errors while reading source files.
 
+    \--include `PATTERN` [ , ... ]
+        Include only files whose paths match one of these
+        PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+    \--omit `PATTERN` [ , ... ]
+        Omit files when their file name matches one of these PATTERNs.
+        Usually needs quoting on the command line.
+
     \-o `OUTFILE`
         Write the XML report to `OUTFILE`. Defaults to ``coverage.xml``.