Skip to content

Commit

Permalink
style(docs): make note:: uses uniform
Browse files Browse the repository at this point in the history
  • Loading branch information
nedbat committed Nov 13, 2021
1 parent ec48227 commit 6a6b604
Show file tree
Hide file tree
Showing 5 changed files with 33 additions and 25 deletions.
8 changes: 5 additions & 3 deletions coverage/control.py
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion doc/api.rst
Expand Up @@ -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.
Expand Down
16 changes: 9 additions & 7 deletions doc/cmd.rst
Expand Up @@ -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 <config_run_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
<config_run_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
Expand Down Expand Up @@ -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
Expand Down
29 changes: 15 additions & 14 deletions doc/source.rst
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/subprocess.rst
Expand Up @@ -19,10 +19,12 @@ begins coverage measurement. The environment variable's value will be used as
the name of the :ref:`configuration file <config>` 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
<python:multiprocessing>`, the ``--concurrency=multiprocessing``
command-line option should take care of everything for you. See
Expand Down

0 comments on commit 6a6b604

Please sign in to comment.