diff --git a/coverage/control.py b/coverage/control.py index 8a832a20e..47e741aa8 100644 --- a/coverage/control.py +++ b/coverage/control.py @@ -933,9 +933,10 @@ def annotate( """Annotate a list of modules. .. note:: - This method has been obsoleted by more modern reporting tools, - including the :meth:`html_report` method. It will be removed in a - future version. + + This method has been obsoleted by more modern reporting tools, + including the :meth:`html_report` method. It will be removed in a + future version. Each module in `morfs` is annotated. The source is written to a new file, named with a ",cover" suffix, with each line prefixed with a @@ -978,6 +979,7 @@ def html_report( Returns a float, the total percentage covered. .. note:: + The HTML report files are generated incrementally based on the source files and coverage results. If you modify the report files, the changes will not be considered. You should be careful about diff --git a/doc/api.rst b/doc/api.rst index f344972a0..855e3ec6f 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -34,7 +34,8 @@ If you want to access the data that coverage.py has collected, the :class:`coverage.CoverageData` class provides an API to read coverage.py data files. -.. Note:: +.. note:: + Only the documented portions of the API are supported. Other names you may find in modules or objects can change their behavior at any time. Please limit yourself to documented methods to avoid problems. diff --git a/doc/cmd.rst b/doc/cmd.rst index d5439f735..189205ef5 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -104,10 +104,11 @@ but before the program invocation:: $ coverage run --source=dir1,dir2 -m packagename.modulename arg1 arg2 .. note:: - Specifying ``--source`` on the ``coverage run`` command line won't affect - subsequent reporting commands like ``coverage xml``. Use the - :ref:`source ` setting in the configuration file to apply - the setting uniformly to all commands. + + Specifying ``--source`` on the ``coverage run`` command line won't affect + subsequent reporting commands like ``coverage xml``. Use the :ref:`source + ` setting in the configuration file to apply the setting + uniformly to all commands. Coverage.py can measure multi-threaded programs by default. If you are using @@ -550,9 +551,10 @@ Text annotation: ``coverage annotate`` -------------------------------------- .. note:: - The **annotate** command has been obsoleted by more modern reporting tools, - including the **html** command. **annotate** will be removed in a future - version. + + The **annotate** command has been obsoleted by more modern reporting tools, + including the **html** command. **annotate** will be removed in a future + version. The **annotate** command produces a text annotation of your source code. With a ``-d`` argument specifying an output directory, each Python file becomes a diff --git a/doc/source.rst b/doc/source.rst index e54ff9954..18eb706c9 100644 --- a/doc/source.rst +++ b/doc/source.rst @@ -30,20 +30,21 @@ the ``[run] source`` configuration value. The value is a comma- or newline-separated list of directories or importable names (packages or modules). -If the source option is specified, -only code in those locations will be measured. -Specifying the source option also enables coverage.py to report on unexecuted -files, since it can search the source tree for files that haven't been measured -at all. Only importable files (ones at the root of the tree, or in directories -with a ``__init__.py`` file) will be considered. Files with unusual punctuation -in their names will be skipped (they are assumed to be scratch files written by -text editors). Files that do not end with ``.py``, ``.pyw``, ``.pyo``, or -``.pyc`` will also be skipped. - -.. note:: Modules named as sources may be imported twice, once by coverage.py - to find their location, then again by your own code or test suite. Usually - this isn't a problem, but could cause trouble if a module has side-effects - at import time. +If the source option is specified, only code in those locations will be +measured. Specifying the source option also enables coverage.py to report on +unexecuted files, since it can search the source tree for files that haven't +been measured at all. Only importable files (ones at the root of the tree, or +in directories with a ``__init__.py`` file) will be considered. Files with +unusual punctuation in their names will be skipped (they are assumed to be +scratch files written by text editors). Files that do not end with ``.py``, +``.pyw``, ``.pyo``, or ``.pyc`` will also be skipped. + +.. note:: + + Modules named as sources may be imported twice, once by coverage.py to find + their location, then again by your own code or test suite. Usually this + isn't a problem, but could cause trouble if a module has side-effects at + import time. You can further fine-tune coverage.py's attention with the ``--include`` and ``--omit`` switches (or ``[run] include`` and ``[run] omit`` configuration diff --git a/doc/subprocess.rst b/doc/subprocess.rst index c09d45f16..b28cbc913 100644 --- a/doc/subprocess.rst +++ b/doc/subprocess.rst @@ -19,10 +19,12 @@ begins coverage measurement. The environment variable's value will be used as the name of the :ref:`configuration file ` to use. .. note:: + The subprocess only sees options in the configuration file. Options set on the command line will not be used in the subprocesses. .. note:: + If you have subprocesses because you are using :mod:`multiprocessing `, the ``--concurrency=multiprocessing`` command-line option should take care of everything for you. See