docs: updated docs for #578 recommendation (#1148)

* updated docs for #578 recommendation 

#578 
https://github.com/nedbat/coveragepy/issues/578#issuecomment-413881957
https://bitbucket.org/suriya/coverage-xml-bug/pull-requests/1/demonstrate-a-fix-to-coverage-xml-bug/diff

also see #1146

* fixed per lint

* updated per lint

1 files changed, 38 insertions, 0 deletions

diff --git a/doc/cmd.rst b/doc/cmd.rst
index b674e298..5957bc11 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -488,6 +488,44 @@ compatible with `Cobertura`_.
 
 You can specify the name of the output file with the ``-o`` switch.
 
+To include complete file paths in the output file, rather than just
+the file name, use [include] vs [source] in your ".coveragerc" file.
+
+For example, use this:
+
+.. code:: ini
+
+    [run]
+    include =
+        foo/*
+        bar/*
+
+
+which will result in
+
+.. code:: xml
+
+    <class branch-rate="0" complexity="0" filename="bar/hello.py" line-rate="1" name="hello.py">
+    <class branch-rate="0" complexity="0" filename="bar/baz/hello.py" line-rate="1" name="hello.py">
+    <class branch-rate="0" complexity="0" filename="foo/hello.py" line-rate="1" name="hello.py">
+
+in place of this:
+
+.. code:: ini
+
+    [run]
+    source =
+        foo
+        bar
+
+which may result in
+
+.. code:: xml
+
+    <class branch-rate="0" complexity="0" filename="hello.py" line-rate="1" name="hello.py">
+    <class branch-rate="0" complexity="0" filename="baz/hello.py" line-rate="1" name="hello.py">
+
+
 Other common reporting options are described above in :ref:`cmd_reporting`.