Skip to content

Commit 9912910

Browse files
tseavertseaver
authored
Prep dns docs for repo split. (#6020)
- Move contents of 'docs/dns/' to 'dns/docs'. - Harmonize / DRY 'dns/README.rst' with 'dns/docs/index.rst'.
1 parent 691b570 commit 9912910

8 files changed

Lines changed: 289 additions & 30 deletions

File tree

‎packages/google-cloud-dns/README.rst‎

Lines changed: 55 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,78 @@
11
Python Client for Google Cloud DNS
22
==================================
33

4-
Python idiomatic client for `Google Cloud DNS`_
4+
The `Google Cloud DNS`_ API provides methods that you can use to
5+
manage DNS for your applications.
56

6-
.. _Google Cloud DNS: https://cloud.google.com/dns/
77

88
|pypi| |versions|
99

10-
- `Documentation`_
10+
- `Client Library Documentation`_
11+
- `Product Documentation`_
1112

12-
.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/dns/usage.html
13+
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-dns.svg
14+
:target: https://pypi.org/project/google-cloud-dns/
15+
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-dns.svg
16+
.. _Google Cloud DNS: https://cloud.google.com/dns/
17+
:target: https://pypi.org/project/google-cloud-dns/
18+
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/dns/index.html
19+
.. _Product Documentation: https://cloud.google.com/dns/docs/
1320

1421
Quick Start
1522
-----------
1623

17-
.. code-block:: console
24+
In order to use this library, you first need to go through the following steps:
1825

19-
$ pip install --upgrade google-cloud-dns
26+
1. `Select or create a Cloud Platform project.`_
27+
2. `Enable billing for your project.`_
28+
3. `Enable the Google Cloud Datastore API.`_
29+
4. `Setup Authentication.`_
2030

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.
31+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
32+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
33+
.. _Enable the Google Cloud Datastore API.: https://cloud.google.com/datastore
34+
.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
2435

25-
.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
36+
Installation
37+
~~~~~~~~~~~~
2638

27-
Authentication
28-
--------------
39+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
40+
create isolated Python environments. The basic problem it addresses is one of
41+
dependencies and versions, and indirectly permissions.
2942

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.
43+
With `virtualenv`_, it's possible to install this library without needing system
44+
install permissions, and without clashing with the installed system
45+
dependencies.
3446

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
47+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
3748

38-
Using the API
39-
-------------
4049

41-
The Cloud `DNS`_ API (`DNS API docs`_) provides methods that you can use to
42-
manage DNS for your applications.
50+
Mac/Linux
51+
^^^^^^^^^
4352

44-
.. _DNS: https://cloud.google.com/dns/
45-
.. _DNS API docs: https://cloud.google.com/dns/docs/apis
53+
.. code-block:: console
4654
47-
See the ``google-cloud-python`` API DNS `Documentation`_ to learn
48-
how to manage DNS records using this Client Library.
55+
pip install virtualenv
56+
virtualenv <your-env>
57+
source <your-env>/bin/activate
58+
<your-env>/bin/pip install google-cloud-datastore
4959
50-
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-dns.svg
51-
:target: https://pypi.org/project/google-cloud-dns/
52-
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-dns.svg
53-
:target: https://pypi.org/project/google-cloud-dns/
60+
61+
Windows
62+
^^^^^^^
63+
64+
.. code-block:: console
65+
66+
pip install virtualenv
67+
virtualenv <your-env>
68+
<your-env>\Scripts\activate
69+
<your-env>\Scripts\pip.exe install google-cloud-datastore
70+
71+
72+
Next Steps
73+
~~~~~~~~~~
74+
75+
- Read the `Client Library Documentation`_ for Google Cloud DNS
76+
API to see other available methods on the client.
77+
- Read the `Product documentation`_ to learn
78+
more about the product and see How-to Guides.

‎packages/google-cloud-dns/docs/changelog.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../dns/CHANGELOG.md

‎packages/google-cloud-dns/docs/changes.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Change Sets
2+
~~~~~~~~~~~
3+
4+
.. automodule:: google.cloud.dns.changes
5+
:members:
6+
:show-inheritance:

‎packages/google-cloud-dns/docs/client.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
DNS Client
2+
==========
3+
4+
.. automodule:: google.cloud.dns.client
5+
:members:
6+
:show-inheritance:

‎packages/google-cloud-dns/docs/index.rst‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
.. include:: /../dns/README.rst
2+
3+
Using the Library
4+
-----------------
5+
6+
Client
7+
~~~~~~
8+
9+
:class:`Client <google.cloud.dns.client.Client>` objects provide a means to
10+
configure your DNS applications. Each instance holds both a ``project``
11+
and an authenticated connection to the DNS service.
12+
13+
For an overview of authentication in ``google-cloud-python``, see :doc:`/core/auth`.
14+
15+
Assuming your environment is set up as described in that document,
16+
create an instance of :class:`Client <google.cloud.dns.client.Client>`.
17+
18+
.. code-block:: python
19+
20+
>>> from google.cloud import dns
21+
>>> client = dns.Client()
22+
23+
Projects
24+
~~~~~~~~
25+
26+
A project is the top-level container in the ``DNS`` API: it is tied
27+
closely to billing, and can provide default access control across all its
28+
datasets. If no ``project`` is passed to the client container, the library
29+
attempts to infer a project using the environment (including explicit
30+
environment variables, GAE, or GCE).
31+
32+
To override the project inferred from the environment, pass an explicit
33+
``project`` to the constructor, or to either of the alternative
34+
``classmethod`` factories:
35+
36+
.. code-block:: python
37+
38+
>>> from google.cloud import dns
39+
>>> client = dns.Client(project='PROJECT_ID')
40+
41+
Project Quotas
42+
~~~~~~~~~~~~~~
43+
44+
Query the quotas for a given project:
45+
46+
.. code-block:: python
47+
48+
>>> from google.cloud import dns
49+
>>> client = dns.Client(project='PROJECT_ID')
50+
>>> quotas = client.quotas() # API request
51+
>>> for key, value in sorted(quotas.items()):
52+
... print('%s: %s' % (key, value))
53+
managedZones: 10000
54+
resourceRecordsPerRrset: 100
55+
rrsetsPerManagedZone: 10000
56+
rrsetAdditionsPerChange: 100
57+
rrsetDeletionsPerChange: 100
58+
totalRrdataSizePerChange: 10000
59+
60+
61+
Project ACLs
62+
^^^^^^^^^^^^
63+
64+
Each project has an access control list granting reader / writer / owner
65+
permission to one or more entities. This list cannot be queried or set
66+
via the API: it must be managed using the Google Developer Console.
67+
68+
69+
Managed Zones
70+
~~~~~~~~~~~~~
71+
72+
A "managed zone" is the container for DNS records for the same DNS name
73+
suffix and has a set of name servers that accept and responds to queries:
74+
75+
.. code-block:: python
76+
77+
>>> from google.cloud import dns
78+
>>> client = dns.Client(project='PROJECT_ID')
79+
>>> zone = client.zone('acme-co', 'example.com',
80+
... description='Acme Company zone')
81+
82+
>>> zone.exists() # API request
83+
False
84+
>>> zone.create() # API request
85+
>>> zone.exists() # API request
86+
True
87+
88+
List the zones for a given project:
89+
90+
.. code-block:: python
91+
92+
>>> from google.cloud import dns
93+
>>> client = dns.Client(project='PROJECT_ID')
94+
>>> zones = client.list_zones() # API request
95+
>>> [zone.name for zone in zones]
96+
['acme-co']
97+
98+
99+
Resource Record Sets
100+
~~~~~~~~~~~~~~~~~~~~
101+
102+
Each managed zone exposes a read-only set of resource records:
103+
104+
.. code-block:: python
105+
106+
>>> from google.cloud import dns
107+
>>> client = dns.Client(project='PROJECT_ID')
108+
>>> zone = client.zone('acme-co', 'example.com')
109+
>>> records, page_token = zone.list_resource_record_sets() # API request
110+
>>> [(record.name, record.record_type, record.ttl, record.rrdatas)
111+
... for record in records]
112+
[('example.com.', 'SOA', 21600, ['ns-cloud1.googlecomains.com dns-admin.google.com 1 21600 3600 1209600 300'])]
113+
114+
.. note::
115+
116+
The ``page_token`` returned from ``zone.list_resource_record_sets()`` will
117+
be an opaque string if there are more resources than can be returned in a
118+
single request. To enumerate them all, repeat calling
119+
``zone.list_resource_record_sets()``, passing the ``page_token``, until
120+
the token is ``None``. E.g.
121+
122+
.. code-block:: python
123+
124+
>>> records, page_token = zone.list_resource_record_sets() # API request
125+
>>> while page_token is not None:
126+
... next_batch, page_token = zone.list_resource_record_sets(
127+
... page_token=page_token) # API request
128+
... records.extend(next_batch)
129+
130+
131+
Change requests
132+
~~~~~~~~~~~~~~~
133+
134+
Update the resource record set for a zone by creating a change request
135+
bundling additions to or deletions from the set.
136+
137+
.. code-block:: python
138+
139+
>>> import time
140+
>>> from google.cloud import dns
141+
>>> client = dns.Client(project='PROJECT_ID')
142+
>>> zone = client.zone('acme-co', 'example.com')
143+
>>> TWO_HOURS = 2 * 60 * 60 # seconds
144+
>>> record_set = zone.resource_record_set(
145+
... 'www.example.com.', 'CNAME', TWO_HOURS, ['www1.example.com.',])
146+
>>> changes = zone.changes()
147+
>>> changes.add_record_set(record_set)
148+
>>> changes.create() # API request
149+
>>> while changes.status != 'done':
150+
... print('Waiting for changes to complete')
151+
... time.sleep(60) # or whatever interval is appropriate
152+
... changes.reload() # API request
153+
154+
155+
List changes made to the resource record set for a given zone:
156+
157+
.. code-block:: python
158+
159+
>>> from google.cloud import dns
160+
>>> client = dns.Client(project='PROJECT_ID')
161+
>>> zone = client.zone('acme-co', 'example.com')
162+
>>> changes = []
163+
>>> changes, page_token = zone.list_changes() # API request
164+
165+
.. note::
166+
167+
The ``page_token`` returned from ``zone.list_changes()`` will be
168+
an opaque string if there are more changes than can be returned in a
169+
single request. To enumerate them all, repeat calling
170+
``zone.list_changes()``, passing the ``page_token``, until the token
171+
is ``None``. E.g.:
172+
173+
.. code-block:: python
174+
175+
>>> changes, page_token = zone.list_changes() # API request
176+
>>> while page_token is not None:
177+
... next_batch, page_token = zone.list_changes(
178+
... page_token=page_token) # API request
179+
... changes.extend(next_batch)
180+
181+
182+
API Reference
183+
-------------
184+
.. toctree::
185+
:maxdepth: 2
186+
187+
client
188+
zone
189+
resource-record-set
190+
changes
191+
192+
Changelog
193+
---------
194+
195+
For a list of all ``google-cloud-dns`` releases:
196+
197+
.. toctree::
198+
:maxdepth: 2
199+
200+
changelog
201+

‎packages/google-cloud-dns/docs/resource-record-set.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Resource Record Sets
2+
~~~~~~~~~~~~~~~~~~~~
3+
4+
.. automodule:: google.cloud.dns.resource_record_set
5+
:members:
6+
:show-inheritance:

‎packages/google-cloud-dns/docs/usage.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<html>
2+
<head>
3+
<meta http-equiv="refresh" content="1; url=./index.html:" />
4+
<script>
5+
window.location.href = "./index.html"
6+
</script>
7+
</head>
8+
</html>

‎packages/google-cloud-dns/docs/zone.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Managed Zones
2+
~~~~~~~~~~~~~
3+
4+
.. automodule:: google.cloud.dns.zone
5+
:members:
6+
:show-inheritance:

0 commit comments

Comments
 (0)