From 45f3d4bca0de2670d126cea5ea9f20a56644f366 Mon Sep 17 00:00:00 2001 From: Derek Schultz Date: Wed, 14 Dec 2016 21:32:16 -0700 Subject: [PATCH] doc updates --- README.md | 95 +++++++++++++++++++++++++++++++++ README.rst | 124 ------------------------------------------- doc/source/index.rst | 4 +- 3 files changed, 97 insertions(+), 126 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 0000000..2c82a40 --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# python-picassoclient + +OpenStack Functions Client Library + +This is a client library for Picasso built on the Picasso API. It +provides a Python API (the ``picassoclient`` module). + +The project is hosted on [Launchpad](https://github.com/iron-io/python-picassoclient/issue), +where bugs can be filed. The code is hosted on [GitHub](https://github.com/iron-io/python-picassoclient). +Patches must be submitted using [Gerrit](http://docs.openstack.org/infra/manual/developers.html#development-workflow), +*not* Github pull requests. + +python-picassoclient is licensed under the Apache License, like the rest of OpenStack. + +## Install the client from PyPI + +The `python-picassoclient` package is published on [PyPI](https://pypi.python.org/pypi/python-picassoclient/) +and can be installed via `pip`. + + $ pip install python-picassoclient + + Note: The packages on PyPI may lag behind the git repo in functionality. + +## Setup the client from source + +1. Clone the source repo + + $ git clone https://github.com/iron-io/python-picassoclient.git + $ cd python-picassoclient + +2. Setup a Python virtualenv + + Note: This is an optional step, but will allow picassoclient dependencies to be installed in a + contained environment that can be easily deleted if you choose to start over or uninstall the client. + + $ tox -evenv --notest + + Activate the virtual environment whenever you want to work in it. + All further commands in this section should be run with the venv active: + + $ source .tox/venv/bin/activate + + When all steps are complete, deactivate the virtualenv by running `deactivate` from your shell. + +3. Install picassoclient and its dependencies:: + + (venv) $ python setup.py develop + +## Picasso CLI + +To work with the CLI, set the necessary Keystone environment variables + + $ export OS_USERNAME= + $ export OS_PASSWORD= + $ export OS_PROJECT_NAME= + $ export OS_AUTH_URL=http://localhost:5000/v3 + + + If working with DevStack, just run `source openrc `. You can then work with a + local installation by passing `--os-token ` and `--os-url http://localhost:9393`. You can + also set up a [Openstackclient](http://docs.openstack.org/developer/python-openstackclient/configuration.html#clouds-yaml) + config file to work with the CLI. + + $ openstack + (openstack) fn apps list + (openstack) fn apps create testapp + + +## Picasso Python API + +Refer to the following code to use Keystone as the authentication backend: + + >>> from keystoneclient.auth.identity import generic + >>> from keystoneclient import session + >>> from picassoclient import client + >>> auth = generic.Password(auth_url=OS_AUTH_URL, username=OS_USERNAME, password=OS_PASSWORD, tenant_name=OS_TENANT_NAME) + >>> keystone_session = session.Session(auth=auth) + >>> picasso = client.Client('v1', session=keystone_session) + >>> picasso.apps.list() + [...] + + +* License: Apache License, Version 2.0 +* Documentation: https://github.com/iron-io/python-picassoclient +* Source: https://github.com/iron-io/python-picassoclient +* Bugs: https://github.com/iron-io/python-picassoclient + +Testing +------- + +There are multiple test targets that can be run to validate the code. + + tox -e pep8 - style guidelines enforcement + tox -e py34 - traditional unit testing + tox -e py35 - traditional unit testing \ No newline at end of file diff --git a/README.rst b/README.rst deleted file mode 100644 index dada719..0000000 --- a/README.rst +++ /dev/null @@ -1,124 +0,0 @@ -======================== -python-picassoclient -======================== - -OpenStack Functions Client Library - -This is a client library for Picasso built on the Picasso API. It -provides a Python API (the ``picassoclient`` module). - -The project is hosted on `Launchpad`_, where bugs can be filed. The code is -hosted on `Github`_. Patches must be submitted using `Gerrit`_, *not* Github -pull requests. - -.. _Github: https://github.com/iron-io/python-picassoclient -.. _Launchpad: https://github.com/iron-io/python-picassoclient/issues -.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow - -python-picassoclient is licensed under the Apache License like the rest of -OpenStack. - -.. contents:: Contents: - :local: - -Install the client from PyPI ----------------------------- -The :program:`python-picassoclient` package is published on `PyPI`_ and -so can be installed using the pip tool, which will manage installing all -python dependencies:: - - $ pip install python-picassoclient - -.. note:: - The packages on PyPI may lag behind the git repo in functionality. - -.. _PyPI: https://pypi.python.org/pypi/python-picassoclient/ - -Setup the client from source ----------------------------- - -* Clone repository for python-picassoclient:: - - $ git clone https://github.com/iron-io/python-picassoclient.git - $ cd python-picassoclient - -* Setup a virtualenv - -.. note:: - This is an optional step, but will allow picassoclient's dependencies - to be installed in a contained environment that can be easily deleted - if you choose to start over or uninstall picassoclient. - -:: - - $ tox -evenv --notest - -Activate the virtual environment whenever you want to work in it. -All further commands in this section should be run with the venv active: - -:: - - $ source .tox/venv/bin/activate - -.. note:: - When ALL steps are complete, deactivate the virtualenv: $ deactivate - -* Install picassoclient and its dependencies:: - - (venv) $ python setup.py develop - -Command-line API ----------------- - -Set Keystone environment variables to execute CLI commands against Picasso. - -* To execute CLI commands:: - - $ export OS_USERNAME= - $ export OS_PASSWORD= - $ export OS_PROJECT_NAME= - $ export OS_AUTH_URL=http://localhost:5000/v3 - -.. note:: - With devstack you just need to $ source openrc . And you can - work with a local installation by passing --os-token and --os-url - http://localhost:9393. You can also set up a `Openstackclient`_ config file - to work with the CLI. - -.. _Openstackclient: http://docs.openstack.org/developer/python-openstackclient/configuration.html#clouds-yaml - -:: - - $ openstack - (openstack) fn-apps list - (openstack) fn-apps create testapp - - -Python API ----------- - -To use with keystone as the authentication system:: - - >>> from keystoneclient.auth.identity import generic - >>> from keystoneclient import session - >>> from picassoclient import client - >>> auth = generic.Password(auth_url=OS_AUTH_URL, username=OS_USERNAME, password=OS_PASSWORD, tenant_name=OS_TENANT_NAME) - >>> keystone_session = session.Session(auth=auth) - >>> picasso = client.Client('v1', session=keystone_session) - >>> picasso.apps.list() - [...] - - -* License: Apache License, Version 2.0 -* Documentation: https://github.com/iron-io/python-picassoclient -* Source: https://github.com/iron-io/python-picassoclient -* Bugs: https://github.com/iron-io/python-picassoclient - -Testing -------- - -There are multiple test targets that can be run to validate the code. - -* tox -e pep8 - style guidelines enforcement -* tox -e py34 - traditional unit testing -* tox -e py35 - traditional unit testing diff --git a/doc/source/index.rst b/doc/source/index.rst index 536cd9c..5a430cb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,9 +1,9 @@ -.. python-laosclient documentation master file, created by +.. python-picassoclient documentation master file, created by sphinx-quickstart on Tue Dec 6 17:37:53 2016. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to python-laosclient's documentation! +Welcome to python-picassoclient's documentation! ============================================= Contents: