Skip to content

Commit 14e4d04

Browse files
tseavertseaver
authored
Declutter sidebar by supplying explict short titles. (googleapis#5939)
Fix up 'resource_manager' docs to avoid propagating sub-menus. Remove Sphinx-only text role from README.
1 parent 2ad3393 commit 14e4d04

4 files changed

Lines changed: 178 additions & 178 deletions

File tree

‎docs/index.rst‎

Lines changed: 35 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,41 @@
11
.. toctree::
2-
:maxdepth: 2
2+
:maxdepth: 1
33
:hidden:
44

5-
releases
6-
core/index
7-
asset/index
8-
automl/index
9-
bigquery/usage
10-
bigquery_datatransfer/index
11-
bigtable/usage
12-
container/index
13-
dataproc/index
14-
datastore/index
15-
dlp/index
16-
dns/usage
17-
firestore/index
18-
iot/index
19-
kms/index
20-
language/index
21-
pubsub/index
22-
oslogin/index
23-
resource-manager/api
24-
runtimeconfig/usage
25-
spanner/index
26-
speech/index
27-
error-reporting/usage
28-
monitoring/index
29-
logging/index
30-
redis/index
31-
storage/index
32-
tasks/index
33-
texttospeech/index
34-
translate/index
35-
vision/index
36-
videointelligence/index
37-
websecurityscanner/index
5+
Core Libraries <core/index>
6+
Asset Management <asset/index>
7+
AutoML <automl/index>
8+
BigQuery <bigquery/usage>
9+
BigQuery Data-Transfer <bigquery_datatransfer/index>
10+
Bigtable <bigtable/usage>
11+
Container <container/index>
12+
Dataproc <dataproc/index>
13+
Datastore <datastore/index>
14+
Data Loss Prevention <dlp/index>
15+
DNS <dns/usage>
16+
Firestore <firestore/index>
17+
IoT <iot/index>
18+
Key Management <kms/index>
19+
Language <language/index>
20+
PubSub <pubsub/index>
21+
OSLogin <oslogin/index>
22+
Redis <redis/index>
23+
Resource Manager <resource-manager/index>
24+
Runtime Configuration <runtimeconfig/usage>
25+
Security Scanner <websecurityscanner/index>
26+
Spanner <spanner/index>
27+
Speech <speech/index>
28+
Storage <storage/index>
29+
Tasks <tasks/index>
30+
Text-to-Speech <texttospeech/index>
31+
Translate <translate/index>
32+
Vision <vision/index>
33+
Video Intelligence <videointelligence/index>
34+
Stackdriver Error Reporting <error-reporting/usage>
35+
Stackdriver Logging <logging/index>
36+
Stackdriver Monitoring <monitoring/index>
37+
Stackdriver Trace <trace/index>
38+
Release History <releases>
3839

3940
Google Cloud Client Library for Python
4041
======================================

‎docs/resource-manager/api.rst‎

Lines changed: 0 additions & 115 deletions
This file was deleted.

‎docs/resource-manager/index.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. include:: /../resource_manager/README.rst
2+
3+
4+
API Reference
5+
-------------
6+
.. toctree::
7+
:maxdepth: 2
8+
:hidden:
9+
10+
client
11+
project
12+
13+
14+
Changelog
15+
---------
16+
17+
For a list of all ``google-cloud-datastore`` releases:
18+
19+
.. toctree::
20+
:maxdepth: 2
21+
22+
changelog

‎resource_manager/README.rst‎

Lines changed: 121 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,148 @@
11
Python Client for Google Cloud Resource Manager
22
===============================================
33

4-
Python idiomatic client for `Google Cloud Resource Manager`_
4+
|pypi| |versions|
55

6-
.. _Google Cloud Resource Manager: https://cloud.google.com/resource-manager/
6+
`Google Cloud Resource Manager`_ API provides methods that you can use
7+
to programmatically manage your projects in the Google Cloud Platform.
8+
With this API, you can do the following:
79

8-
|pypi| |versions|
10+
- Get a list of all projects associated with an account
11+
- Create new projects
12+
- Update existing projects
13+
- Delete projects
14+
- Undelete, or recover, projects that you don't want to delete
15+
16+
- `Client Library Documentation`_
17+
- `Product Documentation`_
18+
19+
20+
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-resource-manager.svg
21+
:target: https://pypi.org/project/google-cloud-resource-manager/
22+
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-resource-manager.svg
23+
:target: https://pypi.org/project/google-cloud-resource-manager/
24+
.. _Google Cloud Resource Manager: https://cloud.google.com/resource-manager/
25+
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/resource-manager/api.html
26+
.. _Product Documentation: https://cloud.google.com/resource-manager/docs/
927

10-
- `Documentation`_
28+
.. note::
1129

12-
.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/resource-manager/api.html
30+
Don't forget to look at the `Authentication`_ section below.
31+
It's slightly different from the rest of this library.
1332

1433
Quick Start
1534
-----------
1635

36+
In order to use this library, you first need to go through the following steps:
37+
38+
1. `Select or create a Cloud Platform project.`_
39+
2. `Enable billing for your project.`_
40+
3. `Enable the Google Cloud Resource Manager API.`_
41+
42+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
43+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
44+
.. _Enable the Google Cloud Resource Manager API.: https://cloud.google.com/resource-manager
45+
46+
Installation
47+
~~~~~~~~~~~~
48+
49+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
50+
create isolated Python environments. The basic problem it addresses is one of
51+
dependencies and versions, and indirectly permissions.
52+
53+
With `virtualenv`_, it's possible to install this library without needing system
54+
install permissions, and without clashing with the installed system
55+
dependencies.
56+
57+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
58+
59+
60+
Mac/Linux
61+
^^^^^^^^^
62+
1763
.. code-block:: console
1864
19-
$ pip install --upgrade google-cloud-resource-manager
65+
pip install virtualenv
66+
virtualenv <your-env>
67+
source <your-env>/bin/activate
68+
<your-env>/bin/pip install google-cloud-resource-manager
2069
21-
For more information on setting up your Python development environment,
22-
such as installing ``pip`` and ``virtualenv`` on your system, please refer
23-
to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
2470
25-
.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
71+
Windows
72+
^^^^^^^
73+
74+
.. code-block:: console
75+
76+
pip install virtualenv
77+
virtualenv <your-env>
78+
<your-env>\Scripts\activate
79+
<your-env>\Scripts\pip.exe install google-cloud-resource-manager
80+
2681
2782
Authentication
28-
--------------
83+
~~~~~~~~~~~~~~
84+
85+
Unlike the other APIs, the Resource Manager API is focused on managing your
86+
various projects inside Google Cloud Platform. What this means (currently, as
87+
of August 2015) is that you can't use a Service Account to work with some
88+
parts of this API (for example, creating projects).
89+
90+
The reason is actually pretty simple: if your API call is trying to do
91+
something like create a project, what project's Service Account can you use?
92+
Currently none.
93+
94+
This means that for this API you should always use the credentials
95+
provided by the `Google Cloud SDK`_, which you can get by running
96+
``gcloud auth login``.
97+
98+
.. _Google Cloud SDK: http://cloud.google.com/sdk
99+
100+
Once you run that command, ``google-cloud-python`` will automatically pick up
101+
the credentials, and you can use the "automatic discovery" feature of the
102+
library.
103+
104+
Start by authenticating:
105+
106+
.. code-block:: bash
29107
30-
With ``google-cloud-python`` we try to make authentication as painless as
31-
possible. Check out the `Authentication section`_ in our documentation to
32-
learn more. You may also find the `authentication document`_ shared by all
33-
the ``google-cloud-*`` libraries to be helpful.
108+
$ gcloud auth login
34109
35-
.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
36-
.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
110+
And then simply create a client:
111+
112+
.. code-block:: python
113+
114+
from google.cloud import resource_manager
115+
client = resource_manager.Client()
37116
38117
Using the API
39118
-------------
40119

41-
The Cloud `Resource Manager`_ API (`Resource Manager API docs`_) provides
42-
methods that you can use to programmatically manage your projects in the
43-
Google Cloud Platform.
120+
Here's a quick example of the full life-cycle:
44121

45-
.. _Resource Manager: https://cloud.google.com/resource-manager/
46-
.. _Resource Manager API docs: https://cloud.google.com/resource-manager/reference/rest/
122+
.. code-block:: python
47123
48-
See the ``google-cloud-python`` API `Resource Manager documentation`_ to learn
49-
how to manage projects using this Client Library.
124+
from google.cloud import resource_manager
50125
51-
.. _Resource Manager documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/resource-manager/api.html
126+
client = resource_manager.Client()
52127
53-
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-resource-manager.svg
54-
:target: https://pypi.org/project/google-cloud-resource-manager/
55-
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-resource-manager.svg
56-
:target: https://pypi.org/project/google-cloud-resource-manager/
128+
# List all projects you have access to
129+
for project in client.list_projects():
130+
print(project)
131+
132+
# Create a new project
133+
new_project = client.new_project(
134+
'your-project-id-here', name='My new project')
135+
new_project.create()
136+
137+
# Update an existing project
138+
project = client.fetch_project('my-existing-project')
139+
project.name = 'Modified name'
140+
project.update()
141+
142+
# Delete a project
143+
project = client.new_project('my-existing-project')
144+
project.delete()
145+
146+
# Undelete a project
147+
project = client.new_project('my-existing-project')
148+
project.undelete()

0 commit comments

Comments
 (0)