Skip to content

Commit 8d437d5

Browse files
gundalowgundalow
committed
Convert README.md to RST
* Update formatting fixes #3 * Add example badge (and how to use) * Make it cleared that bash uploader should be used
1 parent 1e90616 commit 8d437d5

File tree

2 files changed

+150
-100
lines changed

2 files changed

+150
-100
lines changed

‎README.md

Lines changed: 0 additions & 100 deletions
This file was deleted.

‎README.rst

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
[Codecov] Python Example
2+
=========================
3+
4+
.. contents:: Topics
5+
6+
.. image:: https://codecov.io/gh/codecov/example-python/branch/master/graph/badge.svg
7+
:target: https://codecov.io/gh/codecov/example-python
8+
9+
Overview
10+
--------
11+
12+
Main website: `Codecov <https://codecov.io/>`_.
13+
14+
.. code-block:: shell-session
15+
16+
# 1) install codecov
17+
pip install codecov
18+
19+
# 2) next call "codecov" at end of CI build
20+
# public repo using Travis, CircleCI or AppVeyor
21+
codecov
22+
23+
# all other CI and private repositories
24+
codecov --token=<repo token>
25+
26+
27+
You can alternatively use the environment variables:
28+
29+
+----------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
30+
| Argument | Environment | Description |
31+
+==========+===================+====================================================================================================================================================+
32+
| ``-t`` | ``CODECOV_TOKEN`` | Private repo token for uploading |
33+
+----------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
34+
| ``-e`` | ``CODECOV_ENV`` | List of config vars to store for the build |
35+
+----------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
36+
| ``-F`` | | Flag this upload to group coverage reports. Ex. ``unittests`` or ``integration``. `Read the docs <http://docs.codecov.io/docs/flags>`_. |
37+
+----------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
38+
39+
40+
How to generate coverage reports
41+
================================
42+
43+
`coverage.py <https://bitbucket.org/ned/coveragepy>`_ is required to collect coverage metrics.
44+
45+
Below are some examples on how to include coverage tracking during your tests. Codecov will call `coveragexml -i` automatically to generate the coverage xml output, which will be archived and processed server side.
46+
47+
You may need to configure a ``.coveragerc`` file. Learn more `here <http://coverage.readthedocs.org/en/latest/config.html>`_. Start with this `generic .coveragerc <https://gist.github.com/codecov-io/bf15bde2c7db1a011b6e>`_ for example.
48+
49+
We highly suggest adding `source` to your ``.coveragerc`` which solves a number of issues collecting coverage.
50+
51+
.. code-block:: ini
52+
53+
[run]
54+
source=your_package_name
55+
56+
unittests
57+
---------
58+
59+
.. code-block:: shell-session
60+
61+
pip install coverage
62+
coverage run tests.py
63+
64+
pytest
65+
------
66+
67+
.. code-block:: shell-session
68+
69+
ptest --cov=./
70+
71+
nosetests
72+
---------
73+
74+
75+
.. code-block:: shell-session
76+
77+
nosetest --with-coverage
78+
79+
See the `Offical Nose coverage docs <http://nose.readthedocs.org/en/latest/plugins/cover.html>`_ for more information.
80+
81+
Testing with ``tox``
82+
====================
83+
84+
Codecov can be run from inside your ``tox.ini`` please make sure you pass all the necessary environment variables through:
85+
86+
.. code-block:: ini
87+
88+
[testenv]
89+
passenv = CI TRAVIS TRAVIS_*
90+
deps = codecov
91+
commands = codecov
92+
93+
See all the environment variables for `other CI providers <https://github.com/codecov/codecov-bash/blob/master/env>`_.
94+
95+
96+
-------
97+
98+
Frequently Asked Questions
99+
==========================
100+
101+
Whats the different between the codecov-bash and codecov-python uploader?
102+
-------------------------------------------------------------------------
103+
104+
As far as python is concerned, *nothing*. You may choose to use either uploader. Codecov recommends **using the bash uploader when possible** as it supports more unique repository setups.
105+
106+
Learn more at `codecov/codecov-bash <https://github.com/codecov/codecov-bash>`_ and `codecov/codecov-python <https://github.com/codecov/codecov-python>`_.
107+
108+
109+
Why am I seeing ``No data to report.``
110+
--------------------------------------
111+
112+
This output is written by running the command ``coverage xml`` and states that there were no ``.coverage`` files found.
113+
114+
1. Make sure coverage is enabled. See Enabling Coverage
115+
2. You may need to run ``coverage combine`` before running Codecov.
116+
3. Using Docker? Please follow this step: `Testing with Docker: Codecov Inside Docker <https://github.com/codecov/support/wiki/Testing-with-Docker#codecov-inside-docker>`_.
117+
118+
Can I upload my ``.coverage`` files?
119+
------------------------------------
120+
121+
**No**, these files contain coverage data but are not properly mapped back to the source code. We rely on ``coveragepy`` to handle this by calling ``coverage xml`` in the uploader.
122+
123+
How can I integrate with CI/CD providers?
124+
-----------------------------------------
125+
126+
Please see the documentation at our `Python repository <https://github.com/codecov/codecov-python/blob/master/README.md#ci-providers>`_
127+
128+
129+
How do I link to badges?
130+
------------------------
131+
132+
Details on the badges and graphs can be found under `settings/Badge <https://codecov.io/gh/owner/repo/settings/badge>`_, for example the following RST can be used:
133+
134+
.. code-block::
135+
136+
.. image:: https://codecov.io/gh/owner/repo/branch/master/graph/badge.svg
137+
:target: https://codecov.io/gh/owner/repo
138+
139+
140+
Which will generate:
141+
142+
.. image:: https://codecov.io/gh/owner/repo/branch/master/graph/badge.svg
143+
:target: https://codecov.io/gh/owner/repo
144+
145+
Links
146+
=======
147+
148+
* Main website: `Codecov <https://codecov.io/>`_.
149+
* Twitter: `@codecov <https://twitter.com/codecov>`_.
150+
* Email: `hello@codecov.io <hello@codecov.io>`_.

0 commit comments

Comments
 (0)