Merge pull request #31 from osmlab/dev

Merging dev -> master

Author: mattmanley

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+* **Do you want to request a *feature* or report a *bug*?**
+  - [ ] bug report
+  - [ ] feature request
+
+* **What is the current behavior?**
+
+* **If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the 
+problem**
+
+* **What is the expected behavior?**
+
+* **What is the motivation / use case for changing the behavior?**
+
+* **Other information** (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to
+ have context, eg. stackoverflow, gitter, etc)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots & Stack Traces**
+If applicable, add screenshots and/or stack traces to help explain your problem.
+
+**Environment (please complete the following information):**
+ - OS: [e.g. macOS, Windows, Linux]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[Feature Request]"
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+### Description:
+
+Add description here.
+
+### Potential Impact:
+
+List potential impact to downstream libraries here
+
+### Unit Test Approach:
+
+Describe unit tests being added with that PR.
+
+### Test Results:
+
+Describe other (non-unit) test results here.

.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,37 @@
+name: Publish Python 🐍 distributions 📦 to PyPI
+
+on:
+  release:
+    types: [created]
+    branches:
+      - master
+
+jobs:
+  build-n-publish:
+    name: Build and publish Python distributions to PyPI
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@master
+      - name: Set up Python 3.6
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.6
+      - name: Install pep517
+        run: >-
+          python -m
+          pip install
+          pep517
+          --user
+      - name: Build a binary wheel and a source tarball
+        run: >-
+          python -m
+          pep517.build
+          --source
+          --binary
+          --out-dir dist/
+          .
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}

.gitignore

@@ -1,8 +1,10 @@
-tox.ini
 venv
 .eggs
 .idea
 .tox
 *.pyc
 __pycache__
 maproulette.egg-info
+docs/_build
+docs/_static
+docs/_templates

.travis.yml

@@ -7,3 +7,4 @@ install:
 # command to run unit tests
 script:
   - tox
+  - cd docs; make html

README.md

@@ -1 +1,132 @@
-# maproulette-python-client
+# MapRoulette - A Python Client for the MapRoulette API
+
+https://maproulette-python-client.readthedocs.io/
+
+This client makes it easy for users to communicate with the MapRoulette API from within
+their Python environment. In the example below, we are able to access a MapRoulette project in just four lines of code:
+
+```
+   >>> import maproulette
+   >>> config = maproulette.Configuration()
+   >>> api = maproulette.Project(config)
+   >>> api.get_project_by_id(4719)
+   {'data': {'id': 4719, 'owner': 4785024, 'name': 'health_facilities_in_india',...}
+```
+
+The full documentation for this package can be found [here](https://maproulette-python-client.readthedocs.io/). 
+
+
+## Getting Started
+
+Install the package (or add it to your requirements.txt file):
+
+```bash
+pip install maproulette
+```
+
+Import the package:
+
+```
+import maproulette
+```
+
+From there, create a configuration object. Depending on your use case, you may need to pass your API key. Specify
+that when you create your configuration. For example:
+
+```
+config = maproulette.Configuration(api_key='{YOUR_API_KEY}')
+```
+
+Once you have your configuration object we can create an API object using one of several modules depending on the
+functionality that the user is looking for. For example, creating a Project object allows the user to interact with all
+of the project-related functionality in the MapRoulette package.
+
+```
+api = maproulette.Project(config)
+```
+
+Now we have access to the MapRoulette Project API methods. In the example below, I want to find a project by name using
+a search string:
+
+```
+# We want to fetch a project with name 'Health Facilities in India'
+my_project_name = 'Health Facilities in India'
+
+# Pretty-print the API response
+print(json.dumps(api.find_project(my_project_name), indent=4, sort_keys=True))
+```
+
+This returns a nicely printed JSON object representing the project named 'Health Facilities in India':
+
+```
+{
+    "data": [
+        {
+            "created": "2019-08-26T06:34:28.655Z",
+            "deleted": false,
+            "description": "Adding the Hospitals ",
+            "displayName": "Health Facilities in India",
+            "enabled": true,
+            "featured": false,
+            "groups": [
+                {
+                    "created": "2020-03-25T16:23:04.360Z",
+                    "groupType": 1,
+                    "id": 9273,
+                    "modified": "2020-03-25T16:23:04.360Z",
+                    "name": "4719_Admin",
+                    "projectId": 4719
+                },
+                {
+                    "created": "2020-03-25T16:23:04.360Z",
+                    "groupType": 2,
+                    "id": 9274,
+                    "modified": "2020-03-25T16:23:04.360Z",
+                    "name": "4719_Write",
+                    "projectId": 4719
+                },
+                {
+                    "created": "2020-03-25T16:23:04.360Z",
+                    "groupType": 3,
+                    "id": 9275,
+                    "modified": "2020-03-25T16:23:04.360Z",
+                    "name": "4719_Read",
+                    "projectId": 4719
+                }
+            ],
+            "id": 4719,
+            "isVirtual": false,
+            "modified": "2020-01-30T11:05:44.466Z",
+            "name": "health_facilities_in_india",
+            "owner": 4785024
+        }
+    ],
+    "status": 200
+}
+```
+## Development
+
+### Contributing
+
+Open an issue! Thanks for contributing!
+
+### Testing
+
+This package uses [Tox](https://tox.readthedocs.io/en/latest/) to perform testing. In order to run Tox, execute the
+`tox` command from the root directory. 
+
+
+### Building the Documentation
+
+The documentation for this package is built with [Sphinx](https://www.sphinx-doc.org/en/master/index.html). In order to
+build the documentation for this package: 
+
+```
+$ cd docs
+``` 
+and then: 
+```
+$ make html
+```
+That command will generate the HTML documentation files for the project. We've hosted these docs at
+[Read the Docs](https://readthedocs.org/). 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,59 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+from maproulette import __version__
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'maproulette-python-client'
+copyright = ''
+author = ''
+
+# The full version, including alpha/beta/rc tags
+release = __version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc',
+              'sphinx_rtd_theme']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+master_doc = 'index'