3. Contributor Guidelines — Cohen3 0.8.0 documentation

# 3. Contributor Guidelines

## 3.1. Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring.
3. The pull request should work for Python 3.6 and 3.7, and Travis CI.
4. Check https://travis-ci.com/opacam/Cohen3/pull_requests to ensure the tests pass for all supported Python versions and platforms.

## 3.2. Coding Standards

- PEP8
- Write new code in Python 3.

## 3.3. Docstrings

Every module/class/method/function needs a docstring, so use the following keywords when relevant:

- `.. versionadded::` to mark the version in which the feature was added.
- `.. versionchanged::` to mark the version in which the behaviour of the feature was changed.
- `.. note::` to add additional info about how to use the feature or related feature.
- `.. warning::` to indicate a potential issue the user might run into using the feature.

Examples:

    def my_new_feature(self, arg):
        """
        New feature is awesome

        .. versionadded:: 0.8.3

        .. note:: This new feature will likely blow your mind

        .. warning:: Please take a seat before trying this feature
        """

Will result in:

> def my_new_feature(self, arg):

>   New feature is awesome

>   New in version 0.8.3.

>   Note

>   This new feature will likely blow your mind

>   Warning

>   Please take a seat before trying this feature

When referring to other parts of the api use:

- `:mod:`~coherence.module`` to refer to a module
- `:class:`~coherence.module.Class`` to refer to a class
- `:attr:`~coherence.module.Class.attribute`` to refer to a attibute
- `:meth:`~coherence.module.Class.method`` to refer to a method

Obviously replacing module, Class, attribute and method with their real name, and using using ‘.’ to separate modules referring to imbricated modules, e.g:

    :mod:`~coherence.upnp.core.device`
    :class:`~coherence.upnp.core.device.Device`
    :attr:`~coherence.upnp.core.device.Device.services`
    :meth:`~coherence.upnp.core.device.Device.parse_device`

Will result in:

> `device` `Device` `services` `parse_device()`

To build your documentation, enter into docs folder and run:

    $ make html

If you updated your Cohen3 install, and have some trouble compiling docs, run:

    $ make clean
    $ make html

The docs will be generated in `docs/_build/html`. For more information on docstring formatting, please refer to the official Sphinx Documentation.