1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
Creating a Development Environment
==================================
Required Tools
--------------
Python
******
As the OpenStack SDK is developed in Python, you will need at least one
version of Python installed. It is strongly preferred that you have at least
one of version 2 and one of version 3 so that your tests are run against both.
Our continuous integration system runs against several versions, so ultimately
we will have the proper test coverage, but having multiple versions locally
results in less time spent in code review when changes unexpectedly break
other versions.
Python can be downloaded from https://www.python.org/downloads.
virtualenv
**********
In order to isolate our development environment from the system-based Python
installation, we use `virtualenv <https://virtualenv.pypa.io/en/latest/>`_.
This allows us to install all of our necessary dependencies without
interfering with anything else, and preventing others from interfering with us.
Virtualenv must be installed on your system in order to use it, and it can be
had from PyPI, via pip, as follows. Note that you may need to run this
as an administrator in some situations.::
$ apt-get install python-virtualenv # Debian based platforms
$ yum install python-virtualenv # Red Hat based platforms
$ pip install virtualenv # Mac OS X and other platforms
You can create a virtualenv in any location. A common usage is to store all
of your virtualenvs in the same place, such as under your home directory.
To create a virtualenv for the default Python, likely a version 2, run
the following::
$ virtualenv $HOME/envs/sdk
To create an environment for a different version, such as Python 3, run
the following::
$ virtualenv -p python3.4 $HOME/envs/sdk3
When you want to enable your environment so that you can develop inside of it,
you *activate* it. To activate an environment, run the /bin/activate
script inside of it, like the following::
$ source $HOME/envs/sdk3/bin/activate
(sdk3)$
Once you are activated, you will see the environment name in front of your
command prompt. In order to exit that environment, run the ``deactivate``
command.
tox
***
We use `tox <https://tox.readthedocs.org/en/latest/>`_ as our test runner,
which allows us to run the same test commands against multiple versions
of Python. Inside any of the virtualenvs you use for working on the SDK,
run the following to install ``tox`` into it.::
(sdk3)$ pip install tox
Git
***
The source of the OpenStack SDK is stored in Git. In order to work with our
source repository, you must have Git installed on your system. If your
system has a package manager, it can likely be had from there. If not,
you can find downloads or the source at http://git-scm.com.
Getting the Source Code
-----------------------
.. TODO(briancurtin): We should try and distill the following document
into the minimally necessary parts to include directly in this section.
I've talked to several people who are discouraged by that large of a
document to go through before even getting into the project they want
to work on. I don't want that to happen to us because we have the potential
to be more public facing than a lot of other projects.
.. note:: Before checking out the code, please read the OpenStack
`Developer's Guide <http://docs.openstack.org/infra/manual/developers.html>`_
for details on how to use the continuous integration and code
review systems that we use.
The canonical Git repository is hosted on openstack.org at
http://git.openstack.org/cgit/openstack/python-openstacksdk/, with a
mirror on GitHub at https://github.com/openstack/python-openstacksdk.
Because of how Git works, you can create a local clone from either of those,
or your own personal fork.::
(sdk3)$ git clone https://git.openstack.org/openstack/python-openstacksdk.git
(sdk3)$ cd python-openstacksdk
Installing Dependencies
-----------------------
In order to work with the SDK locally, such as in the interactive interpreter
or to run example scripts, you need to install the project's dependencies.::
(sdk3)$ pip install -r requirements.txt
After the downloads and installs are complete, you'll have a fully functional
environment to use the SDK in.
Building the Documentation
--------------------------
Our documentation is written in reStructured Text and is built using
Sphinx. A ``docs`` command is available in our ``tox.ini``, allowing you
to build the documentation like you'd run tests. The ``docs`` command is
not evaluated by default.::
(sdk3)$ tox -e docs
That command will cause the documentation, which lives in the ``docs`` folder,
to be built. HTML output is the most commonly referenced, which is located
in ``docs/build/html``.
|
