We use the ``"""``\ -on-separate-lines style for docstrings:
..code-block:: python
def func(x):
"""
Does something.
:param str x:A very important parameter.
:rtype:str
"""
- If you add or change public APIs, tag the docstring using ``.. versionadded:: 16.0.0 WHAT`` or ``.. versionchanged:: 16.2.0 WHAT``.
- Prefer double quotes (``"``) over single quotes (``'``) unless the string contains double quotes itself.
Tests
-----
- Write your asserts as ``expected == actual`` to line them up nicely:
..code-block:: python
x = f()
assert 42 == x.some_attribute
assert "foo" == x._a_private_attribute
- To run the test suite, all you need is a recent tox_.
It will ensure the test suite runs with all dependencies against all Python versions just as it will on Travis CI.
If you lack some Python versions, you can can always limit the environments like ``tox -e py27,py35`` (in that case you may want to look into pyenv_, which makes it very easy to install many different Python versions in parallel).
- Write `good test docstrings`_.
- To ensure new features work well with the rest of the system, they should be also added to our `Hypothesis`_ testing strategy which you find in ``tests/util.py``.
Documentation
-------------
- Use `semantic newlines`_ in reStructuredText_ files (files ending in ``.rst``):
