rosette-api · Katsuya-Tomioka · Jun 12, 2019 · Jun 4, 2019 · Jun 4, 2019 · Jun 4, 2019
diff --git a/DEVELOPER.md b/DEVELOPER.md
@@ -0,0 +1,42 @@
+## Developer Information
+
+### Testing
+To test changes you have made to the binding, you can use a pre-configured Docker environment.  This environment will:
+- Compile the binding within the container.
+- Install the binding within the container.
+- Execute one or more example files using the installed binding.
+- The example files can be executed against a Cloud release or an Enterprise release.
+- If a test suite exists, it will also be executed.
+
+```
+git clone git@github.com:rosette-api/python.git
+cd python
+# Modify the binding...
+docker run -e API_KEY=$API_KEY -v $(pwd):/source rosetteapi/docker-python
+```
+
+Optional parameters for the `docker run` execution are:
+
+- `-e ALT_URL=<alternative URL>`
+  - For testing against an Enterprise environment or the staging environment.
+- `-e FILENAME=<single filename>`
+  - For testing a single example file instead of all the example files.
+
+To alter the behavior of the pre-configured Docker environment, you can see the Dockerfile source and entry-point
+script [here](https://git.basistech.net/raas/rapid-development-tools/tree/master/binding-dockerfiles). 
+
+### Documentation Generation
+The existing README for documentation generation is [here](docs/README.md).
+The next time the API documentation is touched, please refresh the README and migrate it here.
+
+### Examples README
+There's an old [Docker README](examples/docker) in the examples directory that might be a candidate for removal.
+
+### Building A Release
+See the [instructions](https://git.basistech.net/raas/rapid-development-tools/tree/master/publish)
+
+### TODOs
+- Inconsistent references with `rosette_api` and `rosette-api`
+- Doc generation README cleanup?
+- Example Docker file still needed?
+- `docker-compose.yaml` still needed?
diff --git a/README.md b/README.md
@@ -1,60 +1,38 @@
-[![Build Status](https://travis-ci.org/rosette-api/python.svg?branch=develop)](https://travis-ci.org/rosette-api/python) [![PyPI version](https://badge.fury.io/py/rosette-api.svg)](https://badge.fury.io/py/rosette-api) [![Python Versions](https://img.shields.io/pypi/pyversions/rosette-api.svg?color=dark%20green&label=Python%20Versions)](https://img.shields.io/pypi/pyversions/rosette-api.svg?color=dark%20green&label=Python%20Versions)
-
-## This is the Python client binding for Rosette API.
-You can get an API Key and learn more [here](https://developer.rosette.com).
-For more detailed information check out our [features and functions page](https://developer.rosette.com/features-and-functions).
-
-### Installation
+<a href="https://www.rosette.com"><img src="https://s3.amazonaws.com/styleguide.basistech.com/logos/rosette-logo.png" width="181" height="47" /></a>
 
-The Python binding requires Python 2.7+ or 3.4+ and is available through pip:
+---
 
-`pip install rosette_api`
-
-If the version you are using is not [the latest from PyPI](https://pypi.org/project/rosette_api/#history),
-please check for its [**compatibilty with api.rosette.com**](https://developer.rosette.com/features-and-functions?python).
-If you have an on-premise version of Rosette API server, please contact support for
-binding compatibility with your installation.
-
-To check your installed version:
-
-`pip show rosette_api`
-
-### Basic Usage
+[![Build Status](https://travis-ci.org/rosette-api/python.svg?branch=develop)](https://travis-ci.org/rosette-api/python)
+[![PyPI version](https://badge.fury.io/py/rosette-api.svg)](https://badge.fury.io/py/rosette-api)
+[![Python Versions](https://img.shields.io/pypi/pyversions/rosette-api.svg?color=dark%20green&label=Python%20Versions)](https://img.shields.io/pypi/pyversions/rosette-api.svg?color=dark%20green&label=Python%20Versions)
 
-For help in how to call the various endpoints, please refer to the [examples](https://github.com/rosette-api/python/tree/develop/examples).
+## Rosette API
+The Rosette Text Analytics Platform uses natural language processing, statistical modeling, and machine learning to
+analyze unstructured and semi-structured text across 364 language-encoding-script combinations, revealing valuable
+information and actionable data. Rosette provides endpoints for extracting entities and relationships, translating and
+comparing the similarity of names, categorizing and adding linguistic tags to text and more.
 
-### Supported Endpoints
-- categories
-- entities
-- info
-- language
-- morphology (complete, compound components, han readings, lemmas, parts of speech)
-- name deduplication
-- name similarity
-- name translation
-- ping
-- relationships
-- semantic similarity
-- semantic vectors
-- sentences
-- sentiment
-- syntax dependencies
-- tokens
-- topics
-- transliteration
+## Rosette API Access
+- Rosette Cloud [Sign Up](https://developer.rosette.com/signup)
+- Rosette Enterprise [Evaluation](https://www.rosette.com/product-eval/)
 
-### API Documentation
-See [documentation](http://rosette-api.github.io/python)
+## Quick Start
 
-### Release Notes
-See [wiki](https://github.com/rosette-api/python/wiki/Release-Notes)
-
-### Docker
-A Docker image for running the examples against the compiled source library is available on Docker Hub.
-
-Command: `docker run -e API_KEY=api-key -v "<binding root directory>:/source" rosetteapi/docker-python`
-
-Additional environment settings:
-- `-e ALT_URL=<alternative URL>`
-- `-e FILENAME=<single filename>`
+#### Installation
+`pip install rosette_api`
 
+#### Examples
+View small example programs for each Rosette endpoint
+in the [examples](https://github.com/rosette-api/python/tree/develop/examples) directory.
+
+#### Documentation & Support
+- [Binding API](https://rosette-api.github.io/python/)
+- [Rosette Platform API](https://developer.rosette.com/features-and-functions)
+- [Binding Release Notes](https://github.com/rosette-api/python/wiki/Release-Notes)
+- [Rosette Platform Release Notes](https://support.rosette.com/hc/en-us/articles/360018354971-Release-Notes)
+- [Binding/Rosette Platform Compatibility](https://developer.rosette.com/features-and-functions?python#)
+- [Support](https://support.rosette.com)
+- [Binding License: Apache 2.0](https://github.com/rosette-api/python/blob/develop/LICENSE.txt)
+
+## Binding Developer Information
+If you are modifying the binding code, please refer to the [developer README](https://github.com/rosette-api/python/tree/develop/DEVELOPER.md) file.
diff --git a/examples/README.md b/examples/README.md
@@ -1,44 +1,50 @@
-Python Examples
-==================
-
-These examples are scripts that can be run independently to demonstrate the Rosette API functionality.
-
-Prerequisite: Either run `pip install rosette_api` or run `python setup.py install` in the python top level folder.
-
-Alternatively, you can run all the examples with the command line:
-`find -maxdepth 1 -name "*.py" -exec tox -- {} --key api-key --url alternate_url \;`
-
-You can now run your desired _endpoint_.py file to see it in action.
-For example, run `python/examples/categories.py` if you want to see the categories
-functionality demonstrated.
-
-All files require you to input your Rosette API User Key after --key to run.
-For example: `python ping.py --key 1234567890`
-All also allow you to input your own service URL if desired.
-For example: `python ping.py --key 1234567890 --service_url http://www.myurl.com`
-Some (specified below) allow an additional input of either a file (.html or .txt) or a URL with `--file` or `--url`
-
-Each example, when run, prints its output to the console.
-
-| File Name                     | What it does                                          |
-| -------------                 |-------------                                        |
-| categories.py                    | Gets the category of a document at a URL              |
-| entities.py                      | Gets the entities from a piece of text                |
-| info.py                          | Gets information about Rosette API                    |
-| language.py                      | Gets the language of a piece of text                  |
-| matched-name.py                  | Gets the similarity score of two names                |
-| morphology_complete.py               | Gets the complete morphological analysis of a piece of text|
-| morphology_compound-components.py    | Gets the de-compounded words from a piece of text     |
-| morphology_han-readings.py           | Gets the Chinese words from a piece of text           |
-| morphology_lemmas.py                 | Gets the lemmas of words from a piece of text         |
-| morphology_parts-of-speech.py        | Gets the part-of-speech tags for words in a piece of text |
-| name_deduplication.py                | De-duplicates a list of names |
-| ping.py                          | Pings the Rosette API to check for reachability       |
-| relationships.py                      | Gets the relationships between entities from a piece of text                |
-| sentences.py                     | Gets the sentences from a piece of text               |
-| sentiment.py                     | Gets the sentiment of a local file                    |
-| tokens.py                        | Gets the tokens (words) from a piece of text          |
-| topics.py | Returns key phrases and concepts from provided content |
-| translated-name.py               | Translates a name from one language to another        |
-| transliteration.py               | Transliterates the given text |
-
+## Endpoint Examples
+
+Each example file demonstrates one of the capabilities of the Rosette Platform.
+
+Here are some methods for running the examples.  Each example will also accept an optional `--url` parameter for
+overriding the default URL.
+
+A note on pre-requisites.  Rosette API only supports TLS 1.2 so ensure your toolchain also supports it.
+
+#### Virtualenv/Latest Release
+```
+git clone git@github.com:rosette-api/python.git
+cd python/examples
+virtualenv rosette_venv
+source rosette_venv/bin/activate
+pip install rosette_api
+python ping.py -k $API_KEY
+```
+
+#### Virtualenv/Local Source
+```
+git clone git@github.com:rosette-api/python.git
+cd python
+virtualenv rosette_venv
+source rosette_venv/bin/activate
+python setup.py install
+cd examples
+python ping.py -k $API_KEY
+```
+
+#### Docker/Latest Release
+```
+git clone git@github.com:rosette-api/python.git
+cd python/examples
+docker run -it -v $(pwd):/source --entrypoint bash python:3.6-slim
+cd /source
+pip install rosette_api
+python ping.py -k $API_KEY
+```
+
+#### Docker/Local Source
+```
+git clone git@github.com:rosette-api/python.git
+cd python
+docker run -it -v $(pwd):/source --entrypoint bash python:3.6-slim
+cd /source
+python setup.py install
+cd examples
+python ping.py -k $API_KEY
+```