MSVDD + Bloc

(Microsoft + DataKind AI in Cities Virtual Accelerator - DataDive) + (Bloc)

setup

1. Clone this repository to a directory on your local machine:

   $ cd /path/to/your/preferred/directory
   $ git clone git@github.com:datakind/msvdd_Bloc.git
   $ cd msvdd_Bloc
   

2. Create a virtual environment to isolate our project's dependencies from your other projects'. Use whichever tool you prefer (e.g. virtualenv, pyenv, pipenv). Here's an example using pyenv:

   msvdd_Bloc(master)$ pyenv virtualenv 3.7.4 bloc-env
   msvdd_Bloc(master)$ pyenv shell bloc-env
   

3. Install the package in one of two ways.

   • To use the msvdd_bloc code as-is without further development, installation is simple:

     (bloc-env) msvdd_Bloc(master)$ pip install .
     

   • To further develop the code, install the package in locally-editable (aka develop) mode, plus a few additional dependencies:

     (bloc-env) msvdd_Bloc(master)$ pip install -e .
     (bloc-env) msvdd_Bloc(master)$ pip install -r requirements-dev.txt
     

4. Create a branch with a descriptive name for you to hack on, as needed:

   (bloc-env) msvdd_Bloc(master)$ git pull
   (bloc-env) msvdd_Bloc(master)$ git checkout -b my-example-branch-name
   

documentation

Stand-alone doc files live under the top-level docs/ directory and are written in reStructured Text format. They are built using sphinx:

$ cd docs
$ make html

As needed, commit the latest version of the built HTML docs to the project's master branch:

$ git commit -am "Update built HTML docs"
$ git push origin master

These files are automatically published through GitHub Pages, and are accessible via web browser at https://datakind.github.io/msvdd_Bloc.

In-code docstrings follow Google style. These docstrings are automatically incorporated into the main docs via sphinx.ext.sphinx-autodoc. Refer to the sphinx site for details.

tests

Test modules live under the top-level tests/ directory. They are run using pytest:

$ cd tests
$ pytest -vv .

A coverage report may additionally be generated using pytest-cov:

$ pytest -vv --cov=msvdd_bloc --cov-report=term-missing .

Refer to the pytest site for details.