From b5782ee557e39a8bf1c4c175fc9a0c2395c43d59 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Wed, 19 Sep 2018 10:27:10 -0400
Subject: [PATCH] Prep dns docs for repo split.

- Move contents of 'docs/dns/' to 'dns/docs'.
- Harmonize / DRY 'dns/README.rst' with 'dns/docs/index.rst'.
---
 dns/README.rst                                | 85 ++++++++++++-------
 {docs/dns => dns/docs}/changelog.md           |  0
 {docs/dns => dns/docs}/changes.rst            |  0
 {docs/dns => dns/docs}/client.rst             |  0
 docs/dns/usage.rst => dns/docs/index.rst      | 51 +++++------
 .../dns => dns/docs}/resource-record-set.rst  |  0
 dns/docs/usage.html                           |  8 ++
 {docs/dns => dns/docs}/zone.rst               |  0
 docs/conf.py                                  |  1 +
 docs/dns                                      |  1 +
 docs/index.rst                                |  2 +-
 11 files changed, 89 insertions(+), 59 deletions(-)
 rename {docs/dns => dns/docs}/changelog.md (100%)
 rename {docs/dns => dns/docs}/changes.rst (100%)
 rename {docs/dns => dns/docs}/client.rst (100%)
 rename docs/dns/usage.rst => dns/docs/index.rst (94%)
 rename {docs/dns => dns/docs}/resource-record-set.rst (100%)
 create mode 100644 dns/docs/usage.html
 rename {docs/dns => dns/docs}/zone.rst (100%)
 create mode 120000 docs/dns

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 <your-env>
+    source <your-env>/bin/activate
+    <your-env>/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 <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\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 <google.cloud.dns.client.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 <google.cloud.dns.client.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 @@
+<html>
+<head>
+ <meta http-equiv="refresh" content="1; url=./index.html:" />
+ <script>
+   window.location.href = "./index.html"
+ </script>
+</head>
+</html>
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 <dataproc/index>
   Datastore <datastore/index>
   Data Loss Prevention <dlp/index>
-  DNS <dns/usage>
+  DNS <dns/index>
   Firestore <firestore/index>
   IoT <iot/index>
   Key Management <kms/index>
