Skip to content

Latest commit

 

History

History
146 lines (97 loc) · 3.9 KB

DEVELOPMENT.md

File metadata and controls

146 lines (97 loc) · 3.9 KB
Raw

Development and Testing

For development and testing purposes, it is essential to use a virtual environment. It is recommended that pipenv is used.

Setup Pipenv

To start developing, install pip and pipenv on your system. Note the latter is done at user level to keep the system installation of python clean which is important on a Mac (at least):

sudo easy_install pip

Install pipenv (the --user is important, do not use sudo)

pip install --user pipenv

Check that pipenv is in the binary path

pipenv --version

If not, find the user base binary directory

python -m site --user-base
#~ /Users/<username>/Library/Python/3.7

Append bin to the directory returned and add this to your path by updating ~/.profile. For example you might add the following:

export PATH=~/Library/Python/3.7/bin/:$PATH

Setup Development Environment

Clone GitHub repository

git clone [email protected]:ARMmbed/snippet.git

Setup Pipenv to use Python 3 (Python 2 is not supported) and install package development dependencies:

cd code-snippet/
pipenv --three
pipenv install --dev

Unit Tests, Code Formatting and Static Analysis

Shell into virtual environment:

pipenv shell

Run unit tests:

pytest

Note that other test runners can be used (e.g. green) as long as they support test written using unittest.TestCase.

Run code formatter (it will format files in place):

black .

Run static analysis (note that no output means all is well):

flake8

Perform static type check:

mypy -p snippet

Documenting code

Inclusion of docstrings is needed in all areas of the code for Flake8 checks in the CI to pass.

We use google-style docstrings.

To set up google-style docstring prompts in Pycharm, in the menu navigate to Preferences > Tools > Python Integrated Tools and in the dropdown for docstring format select 'Google'.

For longer explanations, you can also include markdown. Markdown can also be kept in separate files in the docs/user_docs folder and included in a docstring in the relevant place using the reST include as follows:

    .. include:: ../docs/user_docs/documentation.md

Building docs locally

You can do a preview build of the documentation locally by running:

generate-docs

This will generate the docs and output them to local_docs. This should only be a preview. Since documentation is automatically generated by the CI you shouldn't commit any docs html files manually.

Viewing docs generated by the CI

If you want to preview the docs generated by the CI you can view them in the Azure pipeline artifacts directory for the build.

Documentation only gets committed back to this repo to the docs directory during a release and this is what gets published to Github pages. Don't modify any of the files in this directory by hand.

Type hints

Type hints should be used in the code wherever possible. Since the documentation shows the function signatures with the type hints there is no need to include additional type information in the docstrings.

Code Climate

Code Climate is integrated with our GitHub flow. Failing the configured rules will yield a pull request not mergeable.

If you prefer to view the Code Climate report on your machine, prior to sending a pull request, you can use the cli provided by Code Climate.

Plugins for various tools are also available: