docs: explain how to use --debug=trace

Author: nedbat

doc/cmd.rst

@@ -1057,6 +1057,7 @@ a comma-separated list of these options, or in the :ref:`config_run_debug`
 section of the .coveragerc file.
 
 The debug output goes to stderr, unless the ``COVERAGE_DEBUG_FILE`` environment
-variable names a different file, which will be appended to.
+variable names a different file, which will be appended to.  This can be useful
+because many test runners capture output, which could hide important details.
 ``COVERAGE_DEBUG_FILE`` accepts the special names ``stdout`` and ``stderr`` to
 write to those destinations.

doc/faq.rst

@@ -11,6 +11,22 @@ FAQ and other help
 Frequently asked questions
 --------------------------
 
+Q: Why are some of my files not measured?
+.........................................
+
+Coverage.py has a number of mechanisms for deciding which files to measure and
+which to skip.  If your files aren't being measured, use the ``--debug=trace``
+:ref:`option <cmd_run_debug>`, also settable as ``[run] debug=trace`` in the
+:ref:`settings file <config_run_debug>`, or as ``COVERAGE_DEBUG=trace`` in an
+environment variable.
+
+This will write a line for each file considered, indicating whether it is
+traced or not, and if not, why not.  Be careful though: the output might be
+swallowed by your test runner.  If so, a ``COVERAGE_DEBUG_FILE=/tmp/cov.out``
+environemnt variable can direct the output to a file insttead to ensure you see
+everything.
+
+
 Q: Why do unexecutable lines show up as executed?
 .................................................
 

doc/trouble.rst

@@ -25,8 +25,8 @@ bug tracker`_ directly to see if there is some mention of it.
 Things that don't work
 ----------------------
 
-There are a number of popular modules, packages, and libraries that prevent
-coverage.py from working properly:
+There are a few modules or functions that prevent coverage.py from working
+properly:
 
 * `execv`_, or one of its variants.  These end the current program and replace
   it with a new one.  This doesn't save the collected coverage data, so your