Update README and bump version number

CHANGELOG.md

@@ -1,6 +1,12 @@
 Release History
 ===============
 
+0.1.5 Jan 11, 2018
+------------------
+  - Handle non-standard code `iw` for Hebrew used by YouTube API
+  - Better classification of traditional and simplified Chinese scripts
+  - Added basic README
+
 0.1.4 Nov 22, 2017
 ------------------
   - Define constants for all file types

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Learning Equality
+Copyright (c) 2018 Learning Equality
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -1 +1,117 @@
-LE Utils and constants shared across Ricecooker, Kolibri, and Kolibri Studio.
+LE Utils
+========
+Utilities and constants shared across Ricecooker, Kolibri, and Kolibri Studio.
+
+
+
+Languages
+---------
+The file [le_utils/constants/languages.py](./le_utils/constants/languages.py) and
+the lookup table in [le_utils/resources/languagelookup.json](./le_utils/resources/languagelookup.json)
+define the internal representation for languages codes used by Ricecooker, Kolibri,
+and Kolibri Studio to identify educational content in different languages.
+
+The internal representation uses a mixture of two-letter codes (e.g. `en`),
+two-letter-and-country code (e.g. `pt-BR` for Brazilian Portuguese),
+and three-letter codes (e.g., `zul` for Zulu).
+
+In order to make sure you have the correct language code when interfacing with
+the Kolibri ecosystem (e.g. when uploading new content to Kolibri Studio), you
+must lookup the language object using the helper method `getlang`:
+
+```
+>>> from le_utils.constants.languages import getlang
+>>> language_obj = getlang('en')       # lookup language using language code
+>>> language_obj
+Language(native_name='English', primary_code='en', subcode=None, name='English', ka_name=None)
+```
+The function `getlang` will return `None` if the lookup fails. In such cases, you
+can try lookup by name or lookup by alpha2 code (ISO_639-1) methods defined below.
+
+Once you've successfully looked up the language object, you can obtain the internal
+representation language code from the language object's `code` attribute:
+```
+>>> language_obj.code
+'en'
+```
+The Ricecooker API expects these internal representation language codes will be
+supplied for all `language` attributes (channel language, node language, and files language).
+
+
+### More lookup helper methods
+The helper method `getlang_by_name` allows you to lookup a language by name:
+```
+>>> from le_utils.constants.languages import getlang_by_name
+>>> language_obj = getlang_by_name('English')  # lookup language by name
+>>> language_obj
+Language(native_name='English', primary_code='en', subcode=None, name='English', ka_name=None)
+```
+
+The module `le_utils.constants.languages` defines two other language lookup methods:
+  - Use `getlang_by_native_name` for lookup up names by native language name,
+    e.g., you look for 'Français' to find French.
+ -  Use `getlang_by_alpha2` to perform lookups using the standard two-letter codes
+    defined in [ISO_639-1](https://en.wikipedia.org/wiki/ISO_639-1) that are
+    supported by the `pycountries` library.
+
+
+
+Licenses
+--------
+All content nodes within Kolibri and Kolibri Studio must have a license. The file
+[le_utils/constants/licenses.py](./le_utils/constants/licenses.py) contains the
+constants used to identify the license types. These constants are meant to be
+used in conjunction with the helper method `ricecooker.classes.licenses.get_license`
+to create `Licence` objects.
+
+To initialize a license object, you must specify the license type and the
+`copyright_holder` (str) which identifies a person or an organization. For example:
+```
+from ricecooker.classes.licenses import get_license
+from le_utils.constants import licenses
+license = get_license(licenses.CC_BY, copyright_holder="Khan Academy")
+```
+
+Note: The `copyright_holder` field is required for all License types except for
+the public domain license for which `copyright_holder` can be None.
+
+
+
+Content Kinds and File Types
+----------------------------
+The files [le_utils/constants/content_kinds.py](./le_utils/constants/content_kinds.py)
+and [le_utils/constants/file_types.py](./le_utils/constants/file_types.py) contain
+identifiers for the different content types supported by Kolibri and Kolibri Studio.
+
+The currently supported content formats are
+  - Topic node (folder)
+  - Video content nodes backed by a video files
+  - Audio content nodes backed by an audio files
+  - Document content nodes backed by a document files (PDF)
+  - HTML5 app content nodes backed by a HTML5 zip files
+  - Exercise content nodes, which contain different types of questions
+
+
+
+File Formats and Format Presets
+-------------------------------
+The files [le_utils/constants/file_formats.py](./le_utils/constants/file_formats.py)
+and [le_utils/constants/format_presets.py](./le_utils/constants/format_presets.py)
+contain strings used in user interface to identify different file formats.
+
+
+
+Exercises
+---------
+The file [le_utils/constants/exercises.py](./le_utils/constants/exercises.py)
+contains identifiers for different question types and mastery models.
+
+
+
+Proquint Channel Tokens
+-----------------------
+The file [le_utils/proquint.py](./le_utils/proquint.py) contains helper methods
+for generating proquint identifiers for content channels. These are short strings
+that are easy to enter on devices without a full keyboard, e.g. `sutul-hakuh`.
+
+

setup.py

@@ -1,8 +1,10 @@
 from setuptools import find_packages, setup
 
-with open('README.md') as file:
-    long_description = file.read()
-
+try:
+    import pypandoc
+    long_description = pypandoc.convert_file('README.md', 'rst')
+except (IOError, ImportError):
+    long_description = open('README.md').read()
 
 requirements = [
     "pycountry==17.5.14",
@@ -11,15 +13,15 @@
 setup(
     name="le-utils",
     packages = find_packages(),
-    version="0.1.4",
-    description="LE Utils and constants shared across Kolibri, Ricecooker and the Content Curation Server.",
+    version="0.1.5",
+    description="LE Utils and constants shared across Kolibri, Ricecooker, and the Kolibri Studio.",
     long_description=long_description,
     install_requires=requirements,
     license="MIT",
     url="https://github.com/learningequality/le-utils",
     download_url="https://github.com/learningequality/le-utils/releases",
     keywords="le-utils le_utils LE utils kolibri studio ricecooker content curation",
-    package_data={"le_utils": ["resources/*.json"], },
+    package_data={"le_utils": ["resources/*.json"],},
     classifiers=[
         "Development Status :: 2 - Pre-Alpha",
         "Programming Language :: Python",