Rework of Documentation

.gitignore

@@ -11,7 +11,6 @@
 .stestr/
 .testrepository
 .tox
-AUTHORS
 build
 ChangeLog
 dist

.travis.yml

@@ -3,8 +3,6 @@ language: python
 cache: pip
 matrix:
   include:
-  - python: 2.7
-    env: TOXENV=py27
   - python: 3.6
     env: TOXENV=py36
   - python: 3.6

.zuul.yaml

@@ -3,7 +3,7 @@
       jobs:
         - tox-py37
         - tox-pep8
-          #        - tox-docs
+        - tox-docs
         - tox-functional
     gate:
       jobs:

AUTHORS

@@ -0,0 +1,7 @@
+Artem Goncharov <artem.goncharov@t-systems.com>
+György Hodi <hodigy@gmail.com>
+Kristian Kucerak <kucerakk@gmail.com>
+Nils Magnus <magnus@linuxtag.org>
+Tino Schreiber <tino.schreiber@t-systems.com>
+Vineet Pruthi <48789821+vineet-pruthi@users.noreply.github.com>
+Zsolt Nagy <zsoltn@gmail.com>

CONTRIBUTING.rst

@@ -1,45 +1,30 @@
-.. _contributing:
+Contributing to OTC Extensions
+==============================
 
-===================================
-Contributing to python-openstacksdk
-===================================
+OTC Extension are developed as a community effort initiated by
+T-Systems International GmbH for the Open Telekom Cloud under an Open
+Source license. All code is licensed under the Apache 2.0 license.
 
-If you're interested in contributing to the python-openstacksdk project,
-the following will help get you started.
+We are happily accepting pull requests. Please reach out to the
+project to sort out legal code contribution. If you're interested in
+contributing to the project, have a look in the `contributors
+section`_ of our documentation.
 
-Contributor License Agreement
------------------------------
+We follow the recommendation of the `OpenStack's workflow`_ for open
+source contributions and value the four opens.
 
-.. index::
-   single: license; agreement
-
-In order to contribute to the python-openstacksdk project, you need to have
-signed OpenStack's contributor's agreement.
-
-Please read `DeveloperWorkflow`_ before sending your first patch for review.
-Pull requests submitted through GitHub will be ignored.
-
-.. seealso::
-
-   * http://wiki.openstack.org/HowToContribute
-   * http://wiki.openstack.org/CLA
-
-.. _DeveloperWorkflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 Project Hosting Details
--------------------------
+-----------------------
 
 Project Documentation
-    http://docs.openstack.org/sdks/python/openstacksdk/
+    https://python-otcextensions.readthedocs.io/
 
 Bug tracker
-    https://bugs.launchpad.net/python-openstacksdk
-
-Mailing list (prefix subjects with ``[sdk]`` for faster responses)
-    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
+    https://github.com/opentelekomcloud/python-otcextensions/issues
 
 Code Hosting
-    https://git.openstack.org/cgit/openstack/python-openstacksdk
+    https://github.com/opentelekomcloud/python-otcextensions/
 
-Code Review
-    https://review.openstack.org/#/q/status:open+project:openstack/python-openstacksdk,n,z
+.. _contributors section: https://python-otcextensions.readthedocs.io/en/latest/contributor/
+.. _OpenStack's workflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow

README-save

@@ -0,0 +1,137 @@
+OTC Extensions
+==============
+
+.. image:: https://travis-ci.org/OpenTelekomCloud/python-otcextensions.svg?branch=master
+    :target: https://travis-ci.org/OpenTelekomCloud/python-otcextensions
+
+.. image:: https://readthedocs.org/projects/python-otcextensions/badge/?version=latest
+    :target: http://python-otcextensions.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+OTCExtensions is a project to bring OTC extensions into the native OpenStack
+toolstack. Covered are currently following items:
+
+* `python-openstacksdk`
+* `python-openstackclient`
+
+The primary goal is to provide a possibility to use native OpenStack SDK and
+CLI with the OTC additional services
+
+Getting Started
+===============
+
+The very first step to get started is to install otcextensions into your
+system. For this please follow installation instructions_
+
+.. _instructions: http://python-otcextensions.readthedocs.io/en/latest/install/index.html
+
+Next step would be logically configuration
+
+Configuration
+=============
+
+openstack.config
+================
+
+The recommended way, since it is the most efficient way to configure both SDK
+and the CLI in one place
+
+``openstack.config`` will find cloud configuration for as few as 1 clouds and
+as many as you want to put in a config file. It will read environment variables
+and config files, and it also contains some vendor specific default values so
+that you don't have to know extra info to use OpenStack
+
+* If you have a config file, you will get the clouds listed in it
+* If you have environment variables, you will get a cloud named `envvars`
+* If you have neither, you will get a cloud named `defaults` with base defaults
+
+Sometimes an example is nice.
+
+Create a ``clouds.yaml`` file:
+
+.. code-block:: yaml
+
+     clouds:
+      otc:
+        auth:
+          username: 'USER_NAME'
+          password: 'PASS'
+          project_name: 'eu-de'
+          auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3'
+          user_domain_name: 'OTC00000000001000000xxx'
+        interface: 'public'
+        identity_api_version: 3 # !Important
+        ak: 'AK_VALUE' # AK/SK pair for access to OBS
+        sk: 'SK_VALUE'
+
+Please note: ``openstack.config`` will look for a file called ``clouds.yaml``
+in the following locations:
+
+* Current Directory
+* ``~/.config/openstack``
+* ``/etc/openstack``
+
+AK/SK values required for access to some services (i.e. OBS) can be either
+configured as shown above in the clouds.yaml/secure.yaml, or they can be
+automatically retrieved from the S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY.
+Values from the clouds.yaml/secure.yaml take precedence over the ones from
+environment.
+
+With this configuration you can start using openstackCLI simply ``openstack
+--os-cloud otc``
+
+More information at https://developer.openstack.org/sdks/python/openstacksdk/users/config
+
+Old style way
+=============
+
+The CLI can be configured via environment variables and command-line options as
+listed in
+https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html
+or https://developer.openstack.org/sdks/python/openstacksdk/users/config.
+
+Authentication using username/password is often used::
+
+    export OS_AUTH_URL=<url-to-openstack-identity>
+    export OS_IDENTITY_API_VERSION=3
+    export OS_PROJECT_NAME=<project-name>
+    export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
+    export OS_USERNAME=<username>
+    export OS_USER_DOMAIN_NAME=<user-domain-name>
+    export OS_PASSWORD=<password>  # (optional)
+    export S3_ACCESS_KEY_ID=<access_key>
+    export S3_SECRET_ACCESS_KEY=<secret_access_key>
+
+The corresponding command-line options look very similar::
+
+    --os-auth-url <url>
+    --os-identity-api-version 3
+    --os-project-name <project-name>
+    --os-project-domain-name <project-domain-name>
+    --os-username <username>
+    --os-user-domain-name <user-domain-name>
+    [--os-password <password>]
+
+If a password is not provided above (in plaintext), you will be interactively
+prompted to provide one securely.
+
+Authentication may also be performed using an already-acquired token
+and a URL pointing directly to the service API that presumably was acquired
+from the Service Catalog::
+
+    export OS_TOKEN=<token>
+    export OS_URL=<url-to-openstack-service>
+
+The corresponding command-line options look very similar::
+
+    --os-token <token>
+    --os-url <url-to-openstack-service>
+
+In addition to that a regular `clouds.yaml` configuration file can be used
+
+
+Links
+=====
+
+* `Issue Tracker <https://github.com/OpenTelekomCloud/python-otcextensions/issues>`_
+* `Documentation <http://python-otcextensions.readthedocs.io/en/latest/>`_