Development¶
The API is built with Python using Django and Django Rest Framework.
Recommended Development Environment¶
If you are comfortable with setting up a python development environment and cloning the project, feel free to skip to the development environment overview.
Prerequisites¶
We use git for version control and generally follow the development model laid out here. If you are looking for a tool to assist in following this model, we recommend git-flow, a tool made by the same people that created the development model.
This project runs on Python 3.6. You must have Python 3.6 installed to contribute. If you do not have it installed, you can find it here. To manage third-party Python packages, we use pipenv.
Project Setup¶
The first step is to clone the environment:
$ git clone git@github.com:knowmetools/km-api
# Or, if you don't have SSH access
$ git clone https://github.com/knowmetools/km-api
# The remaining commands require you to be in the project directory
$ cd km-api/
If you installed the git-flow
extension, you can now setup the repository to use it:
$ git flow init -d
We also recommend the following configuration options:
$ git config gitflow.feature.finish.keepremote true
$ git config gitflow.bugfix.finish.keepremote true
Finally, install the project requirements
$ pipenv install --dev
The final step is to create a .env
file in the root of your project. This file will be read by any commands executed through pipenv
. For convenience, create the file with the contents:
DJANGO_DEBUG=true
Linting¶
We use a combination of flake8 and black for linting and formatting our code, respectively. To ensure that there are no formatting/linting errors on each commit, we use the pre-commit tool. To install it, simply run:
pipenv run pre-commit install
This will ensure that your code is formatted prior to every commit. If the tool is somehow circumvented or not run, our CI process also runs the same checks and will fail a build that has formatting or linting errors.
Dev Environment Overview¶
Quickstart¶
Clone the project and install the dependencies:
$ git clone git@github.com:knowmetools/km-api
$ cd km-api
$ pipenv install --dev
Local Dev Server¶
The development server can be run using the following command:
$ pipenv run km_api/manage.py runserver
Running Tests¶
Tests are run with pytest. To run the tests, make sure the requirements are installed and run the tests:
$ pipenv install --dev
$ pipenv run pytest km_api/
Building Docs¶
We use sphinx for building documentation, and the docs are automatically published using ReadTheDocs. If you want to build the docs locally, install the requirements and run the build command:
$ pipenv install -r requirements/docs.txt
$ cd docs
$ pipenv run make html