Ned Batchelder  committed 487cad9

Finished the trouble page. Closes issue #226.

  • Participants
  • Parent commits 2754541
  • Branches default

Comments (0)

Files changed (2)

File doc/index.rst

 .. _cover plug-in:
+.. _contact:
 Getting help

File doc/trouble.rst

 .. _trouble:
-When things go wrong
+Things that cause trouble
-Coverage works pretty well, but occasionally things don't go as you would like.
-This page details problems, with links to bug reports if
+:history: 20121231T085200, brand new docs.
-You can of course search the ` bug tracker`_ directly to see if 
-there is some mention of your problem.
+Coverage works well, and I want it to properly measure any Python program, but
+there are some situations it can't cope with.  This page details some known
+problems, with possible courses of action, and links to bug reports
+with more information.
+I would love to :ref:`hear from you <contact>` if you have information about any of
+these problems, even just to explain to me why you want them to start working
+If your problem isn't discussed here, you can of course search the `
+bug tracker`_ directly to see if there is some mention of it.
 .. bug tracker:
+Things that don't work
-There are a number of popular packages that prevent from working 
+There are a number of popular modules, packages, and libraries that prevent from working properly:
-* gevent, `issue 149`_.
+* `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
+  program that calls execv will not be fully measured.  A patch for
+  is in `issue 43`_.
-* execv, or one of its variants, `issue 43`_.
+* `multiprocessing`_ launches processes to provide parallelism.  These
+  processes don't get measured by  Some possible fixes are
+  discussed or linked to in `issue 117`_.
-* multiprocessing, `issue 117`_.
+* `gevent`_, which is based on `greenlet`_, and is similar to `eventlet`_. All
+  of these manipulate the C stack, and therefore confuse
+  `Issue 149`_ has some pointers to more information.
-Code is marked as not executed when I know it is.
+* `sys.settrace`_ is the Python feature that uses to see what's
+  happening in your program.  If another part of your program is using
+  sys.settrace, then it will conflict with, and it won't be
+  measured properly.
-link to DecoratorTools, TurboGears
-Try --timid
-psyco is an issue?
+.. _execv:
+.. _multiprocessing:
+.. _gevent:
+.. _greenlet:
+.. _eventlet:
+.. _sys.settrace:
 .. _issue 43:
 .. _issue 117:
 .. _issue 149:
-Really obscure stuff
+Things that require --timid
+Some packages interfere with coverage measurement, but you might be able to
+make it work by using the ``--timid`` command-line switch, or the ``[run]
+timid=True`` configuration option.
+* `DecoratorTools`_, or any package which uses it, notably `TurboGears`_.
+  DecoratorTools fiddles with the trace function.  You  will need to use
+  ``--timid``.
+.. _DecoratorTools:
+.. _TurboGears:
+Really obscure things
 * Python 2.5 had a bug (`1569356`_) that could make your program behave
   differently when being measured with coverage.  This is diagnosed in `issue 51`_.
 .. _issue 51:
 .. _1569356:
+Still having trouble?
+If your problem isn't mentioned here, and isn't already reported in the ` bug tracker`_,
+please :ref:`get in touch with me <contact>`, we'll figure out a solution.