diff --git a/dns/README.rst b/dns/README.rst index 3ac19dc68379..cfecae06f286 100644 --- a/dns/README.rst +++ b/dns/README.rst @@ -1,53 +1,78 @@ Python Client for Google Cloud DNS ================================== - Python idiomatic client for `Google Cloud DNS`_ +The `Google Cloud DNS`_ API provides methods that you can use to +manage DNS for your applications. -.. _Google Cloud DNS: https://cloud.google.com/dns/ |pypi| |versions| -- `Documentation`_ +- `Client Library Documentation`_ +- `Product Documentation`_ -.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/dns/usage.html +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-dns.svg + :target: https://pypi.org/project/google-cloud-dns/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-dns.svg +.. _Google Cloud DNS: https://cloud.google.com/dns/ + :target: https://pypi.org/project/google-cloud-dns/ +.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/dns/index.html +.. _Product Documentation: https://cloud.google.com/dns/docs/ Quick Start ----------- -.. code-block:: console +In order to use this library, you first need to go through the following steps: - $ pip install --upgrade google-cloud-dns +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Google Cloud Datastore API.`_ +4. `Setup Authentication.`_ -For more information on setting up your Python development environment, -such as installing ``pip`` and ``virtualenv`` on your system, please refer -to `Python Development Environment Setup Guide`_ for Google Cloud Platform. +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Google Cloud Datastore API.: https://cloud.google.com/datastore +.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html -.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup +Installation +~~~~~~~~~~~~ -Authentication --------------- +Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to +create isolated Python environments. The basic problem it addresses is one of +dependencies and versions, and indirectly permissions. -With ``google-cloud-python`` we try to make authentication as painless as -possible. Check out the `Authentication section`_ in our documentation to -learn more. You may also find the `authentication document`_ shared by all -the ``google-cloud-*`` libraries to be helpful. +With `virtualenv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. -.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html -.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication +.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ -Using the API -------------- -The Cloud `DNS`_ API (`DNS API docs`_) provides methods that you can use to -manage DNS for your applications. +Mac/Linux +^^^^^^^^^ -.. _DNS: https://cloud.google.com/dns/ -.. _DNS API docs: https://cloud.google.com/dns/docs/apis +.. code-block:: console -See the ``google-cloud-python`` API DNS `Documentation`_ to learn -how to manage DNS records using this Client Library. + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-datastore -.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-dns.svg - :target: https://pypi.org/project/google-cloud-dns/ -.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-dns.svg - :target: https://pypi.org/project/google-cloud-dns/ + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-datastore + + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Google Cloud DNS + API to see other available methods on the client. +- Read the `Product documentation`_ to learn + more about the product and see How-to Guides. diff --git a/docs/dns/changelog.md b/dns/docs/changelog.md similarity index 100% rename from docs/dns/changelog.md rename to dns/docs/changelog.md diff --git a/docs/dns/changes.rst b/dns/docs/changes.rst similarity index 100% rename from docs/dns/changes.rst rename to dns/docs/changes.rst diff --git a/docs/dns/client.rst b/dns/docs/client.rst similarity index 100% rename from docs/dns/client.rst rename to dns/docs/client.rst diff --git a/docs/dns/usage.rst b/dns/docs/index.rst similarity index 94% rename from docs/dns/usage.rst rename to dns/docs/index.rst index 416a1c39fcaa..1f63d71155d8 100644 --- a/docs/dns/usage.rst +++ b/dns/docs/index.rst @@ -1,26 +1,10 @@ -DNS -=== +.. include:: /../dns/README.rst -.. toctree:: - :maxdepth: 2 - :hidden: - - client - zone - resource-record-set - changes - -Installation ------------- - -Install the ``google-cloud-dns`` library using ``pip``: - -.. code-block:: console - - $ pip install google-cloud-dns +Using the Library +----------------- Client ------- +~~~~~~ :class:`Client ` objects provide a means to configure your DNS applications. Each instance holds both a ``project`` @@ -37,7 +21,7 @@ create an instance of :class:`Client `. >>> client = dns.Client() Projects --------- +~~~~~~~~ A project is the top-level container in the ``DNS`` API: it is tied closely to billing, and can provide default access control across all its @@ -55,7 +39,7 @@ To override the project inferred from the environment, pass an explicit >>> client = dns.Client(project='PROJECT_ID') Project Quotas --------------- +~~~~~~~~~~~~~~ Query the quotas for a given project: @@ -75,7 +59,7 @@ Query the quotas for a given project: Project ACLs -~~~~~~~~~~~~ +^^^^^^^^^^^^ Each project has an access control list granting reader / writer / owner permission to one or more entities. This list cannot be queried or set @@ -83,7 +67,7 @@ via the API: it must be managed using the Google Developer Console. Managed Zones -------------- +~~~~~~~~~~~~~ A "managed zone" is the container for DNS records for the same DNS name suffix and has a set of name servers that accept and responds to queries: @@ -113,7 +97,7 @@ List the zones for a given project: Resource Record Sets --------------------- +~~~~~~~~~~~~~~~~~~~~ Each managed zone exposes a read-only set of resource records: @@ -145,7 +129,7 @@ Each managed zone exposes a read-only set of resource records: Change requests ---------------- +~~~~~~~~~~~~~~~ Update the resource record set for a zone by creating a change request bundling additions to or deletions from the set. @@ -194,13 +178,24 @@ List changes made to the resource record set for a given zone: ... page_token=page_token) # API request ... changes.extend(next_batch) + +API Reference +------------- +.. toctree:: + :maxdepth: 2 + + client + zone + resource-record-set + changes + Changelog --------- For a list of all ``google-cloud-dns`` releases: .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - changelog + changelog diff --git a/docs/dns/resource-record-set.rst b/dns/docs/resource-record-set.rst similarity index 100% rename from docs/dns/resource-record-set.rst rename to dns/docs/resource-record-set.rst diff --git a/dns/docs/usage.html b/dns/docs/usage.html new file mode 100644 index 000000000000..9b81d6976cda --- /dev/null +++ b/dns/docs/usage.html @@ -0,0 +1,8 @@ + + + + + + diff --git a/docs/dns/zone.rst b/dns/docs/zone.rst similarity index 100% rename from docs/dns/zone.rst rename to dns/docs/zone.rst diff --git a/docs/conf.py b/docs/conf.py index 8d5a573c03a8..c3c75d0e07ef 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -330,6 +330,7 @@ # HTML pages to be copied from source to target static_html_pages = [ 'datastore/usage.html', + 'dns/usage.html', 'bigquery/usage.html', 'spanner/usage.html', ] diff --git a/docs/dns b/docs/dns new file mode 120000 index 000000000000..9eea51dc71fe --- /dev/null +++ b/docs/dns @@ -0,0 +1 @@ +../dns/docs \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 1e7560c3db26..ac6aa66756a6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ Dataproc Datastore Data Loss Prevention - DNS + DNS Firestore IoT Key Management