feat(package) upgrade to modern packaging (#6)

** FEATURE DETAILS **

- Introduce the following recent packaging good practices:
  - move package metadata to setup.cfg
  - move requirements to setup.cfg
  - check setup.cfg quality with pyroma
- Add PyPI configuration to upload Fonzie package upon tagging
- Update installation documentation

** TODO **

Document the Fun-platform way to install a third-party Django
application (using Docker).

.travis.yml

@@ -1,38 +1,30 @@
-# Config file for automatic testing at travis-ci.org
 sudo: required
-
 language: python
-
 cache:
   directories:
-    - $HOME/.cache/db
-    - node_modules
-
+  - "$HOME/.cache/db"
+  - node_modules
 env:
-  - TOXENV=quality
-  - TOXENV=docs
-  - TOXENV=django18
-  - API_SPEC=1 OPENEDX_RELEASE=ginkgo.1
-
+- TOXENV=quality
+- TOXENV=docs
+- TOXENV=django18
+- API_SPEC=1 OPENEDX_RELEASE=ginkgo.1
 before_install:
-  # Upgrade docker-compose
-  - bin/ci before-install
-
+- bin/ci before-install
 install:
-  - bin/ci install
-
+- bin/ci install
 script:
-  - bin/ci script
-
+- bin/ci script
 after_success:
-  - bin/ci after-success
-
-# Set password via "travis encrypt --add deploy.password"; for details, see
-# https://docs.travis-ci.com/user/deployment/pypi
+- bin/ci after-success
 deploy:
   provider: pypi
-  user: edx
+  user: openfun
   distributions: sdist bdist_wheel
   on:
     tags: true
-    condition: '$TOXENV = quality'
+    condition: "$TOXENV = quality"
+  # Encrypted password set via "travis encrypt --add deploy.password"; for
+  # details, see https://docs.travis-ci.com/user/deployment/pypi
+  password:
+    secure: Oa6dtKi4mbJfMkduQmwZRwPH9Nu8FRJKas1xdaTfhrKlj0wr4+4IfEp0Vn9egyeamS94r06KlwSWN3c8PVIlPV7noUeewA5jAPYSdGbFCmOxNGgr3BQh1GL4mF/kxoQmG9GdeEoNOuBhbMtHOIbHIB8fH+ct8zCsNxW0xMjSRbioCEiQTD8FdDIPjXIg4W/cqJ08A1nFNhrVVSRV5gUa9LAH1S5eA9+GmyAB9kwSZXcbqF3imyRUpGPTLMGlb0qgrPLnCgtbh+GgyN5SFpL4USqrgjpNddCv9EYKgJ3ulALqPIuwbVgjt5KdYt/4cDpaHtc53lHpVpYsZmGCwcdizTvJgOZzaN9FAmJjdNdFBHBO0whb7QVrDE4rRmKqlMf5vTqFH15jkRZtRkyvHowjbBMUtJ2qsmNBVUWax20l/2RH3lwk2MW1goC1XrOg/eymjLSMAM97voIu1EO1RSql94avg/xXLRzfftjvqB4VvdJOPuXoZkJlKimiFPJP3O+yYubpBGBotabSRSGGBhRpOLD5vbRGdx4qI+gvCyiLlD0T4+pFQ+LXucD8Y/GrxT8CFWAM5lUMFGQQNikNizKQOxCnGZhRtyTzhwCZ84PmFr0XIrOYrxCvELCZlA1sUDptdx8W6gQbFF+znKrhLbffomd3dtpPRq/qo+CO7UVmxtg=

Dockerfile

@@ -19,18 +19,12 @@ RUN curl -L \
     tar -C /usr/local/bin -xzvf dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz && \
     rm dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz
 
-# Install project requirements
-ADD ./requirements /app/fonzie/requirements
-RUN pip install -q --exists-action w \
-        -r /app/fonzie/requirements/dev.txt \
-        -r /app/fonzie/requirements/private.*
-
 # Add application sources
 ADD . /app/fonzie/
 
-# Install django application in development mode
+# Install application and project requirements
 RUN cd /app/fonzie && \
-    pip install -e .
+    pip install --exists-action w -r requirements.txt
 
 # FIXME: pyopenssl seems to be linked with a wrong openssl release leading to
 # bad handskake ssl errors. This looks ugly, but forcing pyopenssl

Makefile

@@ -1,6 +1,6 @@
 .PHONY: clean compile_translations coverage docs dummy_translations \
 	extract_translations fake_translations help pull_translations push_translations \
-	quality requirements run selfcheck stop test test-all upgrade validate
+	quality requirements run selfcheck stop test test-all validate
 
 .DEFAULT_GOAL := help
 
@@ -64,17 +64,6 @@ docs: ## generate Sphinx HTML documentation, including API docs
 	$(TOX) -e docs
 	$(BROWSER) docs/_build/html/index.html
 
-upgrade: ## update the requirements/*.txt files with the latest packages satisfying requirements/*.in
-	$(PIP) install -q pip-tools
-	$(PIP-COMPILE) --upgrade -o requirements/dev.txt requirements/base.in requirements/dev.in requirements/quality.in
-	$(PIP-COMPILE) --upgrade -o requirements/doc.txt requirements/base.in requirements/doc.in
-	$(PIP-COMPILE) --upgrade -o requirements/quality.txt requirements/quality.in
-	$(PIP-COMPILE) --upgrade -o requirements/test.txt requirements/base.in requirements/test.in
-	$(PIP-COMPILE) --upgrade -o requirements/travis.txt requirements/travis.in
-	# Let tox control the Django version for tests
-	$(COMPOSE_RUN_FONZIE) sed '/^django==/d' requirements/test.txt > requirements/test.tmp
-	$(COMPOSE_RUN_FONZIE) mv requirements/test.tmp requirements/test.txt
-
 quality: ## check coding style with pycodestyle and pylint
 	$(TOX) -e quality
 

docs/conf.py

@@ -26,23 +26,12 @@
 from django.conf import settings
 from django.utils import six
 
-
-def get_version(*file_paths):
-    """
-    Extract the version string from the file at the given relative path fragments.
-    """
-    filename = os.path.join(os.path.dirname(__file__), *file_paths)
-    version_file = open(filename).read()    # pylint: disable=open-builtin
-    version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", version_file, re.M)
-    if version_match:
-        return version_match.group(1)
-    raise RuntimeError('Unable to find version string.')
-
+from ..fonzie import __version__ as package_version
 
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 sys.path.append(REPO_ROOT)
 
-VERSION = get_version('../fonzie', '__init__.py')
+VERSION = package_version
 
 # Configure Django for autodoc usage
 settings.configure()

docs/getting_started.rst

@@ -1,74 +1,85 @@
 Getting Started
 ===============
 
-If you have not already done so, create/activate a `virtualenv`_. Unless otherwise stated, assume all terminal code
-below is executed within the virtualenv.
+Fonzie is supposed to be installed as a Django application running in an Open
+edX platform instance. Fonzie has been designed to be integrated with the
+current Open edX release (Ginkgo at the time of writing). We plan to support the
+next Open edX release (Hawthorn) in a near future.
 
-.. _virtualenv: https://virtualenvwrapper.readthedocs.org/en/latest/
+Pre-requisites for Fonzie contributors
+--------------------------------------
 
-
-Pre-requisites
---------------
-
-We are using `Dredd <http://dredd.readthedocs.io/en/latest/>`_ to test our API
-implementation. It requires `Node.js <https://nodejs.org/en/>`_ to run and we
-are using `Yarn <https://yarnpkg.com/en/>`_ to install it. So make sure both
-``node`` and ``yarn`` are installed and functionnal before pursuing this
-installation.
+We extensively use `Docker <https://docs.docker.com/install/>`_ (17.12+) and
+`Docker compose <https://docs.docker.com/compose/install/>`_ (1.18+) in our
+development workflow. So, if you intend to work on Fonzie, please, make sure they
+are both installed and functionnal before pursuing this installation.
 
 Install dependencies
 --------------------
 
-Dependencies can be installed via `pip` in your project's virtual environment:
-
-.. code-block:: bash
+To install Fonzie in an Open edX project, two choices are offered depending on
+the way you are running your instance. If Open edX runs as a suite of Docker
+containers, Fonzie's development environment can serve as an example of how to
+integrate a Django application in `fun-platform
+<https://github.com/openfun/fun-platform>`_'s docker stack. Alternatively, if
+you are running Open edX on a bare metal server (or virtual machine), the
+installation protocol follows a standard Django procedure that will be described
+below.
 
-    # Create a python 2.7 virtual environment
-    $ virtualenv venv
+Standard procedure
+^^^^^^^^^^^^^^^^^^
 
-    # Activate your virtual environment
-    $ source venv/bin/activate
+Install fonzie and its dependencies in your Open edX installation with ``pip``:
 
-    # Install fonzie and its dependencies in your virtualenv
-    (venv) $ pip install fonzie
+.. code-block:: bash
 
-Alternatively, if you intend to work on this project, clone the repository first and then
-install requirements _via_ the command below:
+    $ (sudo) pip install fonzie
 
-.. code-block:: bash
+Docker procedure
+^^^^^^^^^^^^^^^^
 
-    $ git clone git@github.com:openfun/fonzie.git
-    (venv) $ make requirements
+TODO
 
 Configure Fonzie
 ----------------
 
-Edit the settings of your project  (_e.g._ ``my_project/settings.py``) by adding
+Once installed, Fonzie needs to be configured as a standard Django application,
+_i.e._ adding ``fonzie`` to your ``INSTALLED_APPS`` and Fonzie's URLs to your
+project's URLs. Achieving those two steps depends on the way you are running
+Open edX.
+
+Standard procedure
+^^^^^^^^^^^^^^^^^^
+
+Edit the LMS settings of your Open edX instance  (_e.g._ ``lms/envs/private.py``) by adding
 ``fonzie`` to your ``INSTALLED_APPS`` and configure Django Rest Framework (_aka_
 DRF) API versioning support as follows:
 
 .. code-block:: python
 
-    # my_project/settings.py
-
-    INSTALLED_APPS = (
-        # [...]
+    # lms/env/private.py
+    INSTALLED_APPS += (
         'fonzie',
     )
 
     # Django Rest Framework (aka DRF)
-    REST_FRAMEWORK = {
+    REST_FRAMEWORK.update({
         'ALLOWED_VERSIONS': ('1.0', ),
         'DEFAULT_VERSION': '1.0',
         'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
-    }
+    })
 
-And finally, configure Fonzie urls for your project:
+And finally, add Fonzie urls in Open edX LMS's URLs:
 
 .. code-block:: python
 
-    # my_project/urls.py
+    # lms/urls.py
     urlpatterns = [
         # [...]
         url(r'^api/', include('fonzie.urls')),
     ]
+
+Docker procedure
+^^^^^^^^^^^^^^^^
+
+TODO

fonzie/__init__.py

@@ -1,9 +1,29 @@
 """
 Fonzie, A FUN API for Open edX.
 """
-
 from __future__ import absolute_import, unicode_literals
 
-__version__ = '0.1.0'
+from os import path
+from setuptools.config import read_configuration
+
+import pkg_resources
+
+
+def _extract_version(package_name):
+    """
+    Extract fonzie version.
+
+    Get package version from installed distribution or configuration file if not installed
+    """
+    try:
+        return pkg_resources.get_distribution(package_name).version
+    except pkg_resources.DistributionNotFound:
+        _conf = read_configuration(
+            path.join(path.dirname(path.dirname(__file__)), 'setup.cfg')
+        )
+    return _conf['metadata']['version']
+
+
+__version__ = _extract_version('fonzie')
 
 default_app_config = 'fonzie.apps.FonzieConfig'  # pylint: disable=invalid-name

requirements.txt

@@ -0,0 +1 @@
+-e .[dev,doc,quality,test,travis]