Re-organize the documentation structure in preparation to split docs …

…among subpackages (googleapis#3459)
landrito · Aug 22, 2017 · 887a6cd · 887a6cd
1 parent 3d6adcd
commit 887a6cd
Show file tree

Hide file tree

Showing 142 changed files with 449 additions and 457 deletions.
diff --git a/docs/bigquery-client.rst → docs/bigquery/client.rst b/docs/bigquery-client.rst → docs/bigquery/client.rst
@@ -1,5 +1,5 @@
-BigQuery Client
-===============
+Client
+======
 
 .. automodule:: google.cloud.bigquery.client
   :members:

diff --git a/docs/bigquery-dataset.rst → docs/bigquery/dataset.rst b/docs/bigquery-dataset.rst → docs/bigquery/dataset.rst
diff --git a/docs/bigquery-job.rst → docs/bigquery/job.rst b/docs/bigquery-job.rst → docs/bigquery/job.rst
diff --git a/docs/bigquery-query.rst → docs/bigquery/query.rst b/docs/bigquery-query.rst → docs/bigquery/query.rst
diff --git a/docs/bigquery-schema.rst → docs/bigquery/schema.rst b/docs/bigquery-schema.rst → docs/bigquery/schema.rst
diff --git a/docs/bigquery_snippets.py → docs/bigquery/snippets.py b/docs/bigquery_snippets.py → docs/bigquery/snippets.py
diff --git a/docs/bigquery-table.rst → docs/bigquery/table.rst b/docs/bigquery-table.rst → docs/bigquery/table.rst
diff --git a/docs/bigquery-usage.rst → docs/bigquery/usage.rst b/docs/bigquery-usage.rst → docs/bigquery/usage.rst
@@ -1,5 +1,16 @@
-Using the API
-=============
+BigQuery
+========
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  client
+  dataset
+  job
+  query
+  schema
+  table
 
 Authentication / Configuration
 ------------------------------
@@ -71,31 +82,31 @@ Dataset operations
 
 List datasets for the client's project:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START client_list_datasets]
    :end-before: [END client_list_datasets]
 
 Create a new dataset for the client's project:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START dataset_create]
    :end-before: [END dataset_create]
 
 Check for the existence of a dataset:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START dataset_exists]
    :end-before: [END dataset_exists]
 
 Refresh metadata for a dataset (to pick up changes made by another client):
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START dataset_reload]
    :end-before: [END dataset_reload]
 
 Patch metadata for a dataset:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START dataset_patch]
    :end-before: [END dataset_patch]
 
@@ -114,7 +125,7 @@ Replace the ACL for a dataset, and update all writeable fields:
 
 Delete a dataset:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START dataset_delete]
    :end-before: [END dataset_delete]
 
@@ -124,61 +135,61 @@ Tables
 
 Tables exist within datasets.  List tables for the dataset:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START dataset_list_tables]
    :end-before: [END dataset_list_tables]
 
 Create a table:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_create]
    :end-before: [END table_create]
 
 Check for the existence of a table:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_exists]
    :end-before: [END table_exists]
 
 Refresh metadata for a table (to pick up changes made by another client):
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_reload]
    :end-before: [END table_reload]
 
 Patch specific properties for a table:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_patch]
    :end-before: [END table_patch]
 
 Update all writable metadata for a table
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_update]
    :end-before: [END table_update]
 
 Get rows from a table's data:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_fetch_data]
    :end-before: [END table_fetch_data]
 
 Insert rows into a table's data:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_insert_data]
    :end-before: [END table_insert_data]
 
 Upload table data from a file:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_upload_from_file]
    :end-before: [END table_upload_from_file]
 
 Delete a table:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START table_delete]
    :end-before: [END table_delete]
 
@@ -195,7 +206,7 @@ Jobs describe actions peformed on data in BigQuery tables:
 
 List jobs for a project:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START client_list_jobs]
    :end-before: [END client_list_jobs]
 
@@ -205,29 +216,29 @@ Querying data (synchronous)
 
 Run a query which can be expected to complete within bounded time:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START client_run_sync_query]
    :end-before: [END client_run_sync_query]
 
 Run a query using a named query parameter:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START client_run_sync_query_w_param]
    :end-before: [END client_run_sync_query_w_param]
 
 If the rows returned by the query do not fit into the initial response,
 then we need to fetch the remaining rows via
 :meth:`~google.cloud.bigquery.query.QueryResults.fetch_data`:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START client_run_sync_query_paged]
    :end-before: [END client_run_sync_query_paged]
 
 If the query takes longer than the timeout allowed, ``query.complete``
 will be ``False``.  In that case, we need to poll the associated job until
 it is done, and then fetch the results:
 
-.. literalinclude:: bigquery_snippets.py
+.. literalinclude:: snippets.py
    :start-after: [START client_run_sync_query_timeout]
    :end-before: [END client_run_sync_query_timeout]
 

diff --git a/docs/bigtable-client-intro.rst → docs/bigtable/client-intro.rst b/docs/bigtable-client-intro.rst → docs/bigtable/client-intro.rst
@@ -23,7 +23,7 @@ Configuration
 -------------
 
 - For an overview of authentication in ``google-cloud-python``,
-  see :doc:`google-cloud-auth`.
+  see :doc:`/core/auth`.
 
 - In addition to any authentication configuration, you can also set the
   :envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the Google Cloud Console
@@ -84,7 +84,7 @@ After a :class:`Client <google.cloud.bigtable.client.Client>`, the next highest-
 object is an :class:`Instance <google.cloud.bigtable.instance.Instance>`. You'll need
 one before you can interact with tables or data.
 
-Head next to learn about the :doc:`bigtable-instance-api`.
+Head next to learn about the :doc:`instance-api`.
 
 .. _Instance Admin: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/tree/master/bigtable-protos/src/main/proto/google/bigtable/admin/instance/v1
 .. _Table Admin: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/tree/master/bigtable-protos/src/main/proto/google/bigtable/admin/table/v1
diff --git a/docs/bigtable-client.rst → docs/bigtable/client.rst b/docs/bigtable-client.rst → docs/bigtable/client.rst
diff --git a/docs/bigtable-cluster.rst → docs/bigtable/cluster.rst b/docs/bigtable-cluster.rst → docs/bigtable/cluster.rst
diff --git a/docs/bigtable-column-family.rst → docs/bigtable/column-family.rst b/docs/bigtable-column-family.rst → docs/bigtable/column-family.rst
diff --git a/docs/bigtable-data-api.rst → docs/bigtable/data-api.rst b/docs/bigtable-data-api.rst → docs/bigtable/data-api.rst
@@ -7,7 +7,7 @@ column families, you are ready to store and retrieve data.
 Cells vs. Columns vs. Column Families
 +++++++++++++++++++++++++++++++++++++
 
-* As explained in the :doc:`table overview <bigtable-table-api>`, tables can
+* As explained in the :doc:`table overview <table-api>`, tables can
   have many column families.
 * As described below, a table can also have many rows which are
   specified by row keys.

diff --git a/docs/bigtable-instance-api.rst → docs/bigtable/instance-api.rst b/docs/bigtable-instance-api.rst → docs/bigtable/instance-api.rst
@@ -123,7 +123,7 @@ Now we go down the hierarchy from
 :class:`Instance <google.cloud.bigtable.instance.Instance>` to a
 :class:`Table <google.cloud.bigtable.table.Table>`.
 
-Head next to learn about the :doc:`bigtable-table-api`.
+Head next to learn about the :doc:`table-api`.
 
 .. _Instance Admin API: https://cloud.google.com/bigtable/docs/creating-instance
 .. _CreateInstance: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/instance/v1/bigtable_instance_service.proto#L66-L68

diff --git a/docs/bigtable-instance.rst → docs/bigtable/instance.rst b/docs/bigtable-instance.rst → docs/bigtable/instance.rst
diff --git a/docs/bigtable-row-data.rst → docs/bigtable/row-data.rst b/docs/bigtable-row-data.rst → docs/bigtable/row-data.rst
diff --git a/docs/bigtable-row-filters.rst → docs/bigtable/row-filters.rst b/docs/bigtable-row-filters.rst → docs/bigtable/row-filters.rst
diff --git a/docs/bigtable-row.rst → docs/bigtable/row.rst b/docs/bigtable-row.rst → docs/bigtable/row.rst
diff --git a/docs/bigtable-table-api.rst → docs/bigtable/table-api.rst b/docs/bigtable-table-api.rst → docs/bigtable/table-api.rst
@@ -98,7 +98,7 @@ or similar):
 This rule helps the backend determine when and how to clean up old cells
 in the column family.
 
-See :doc:`bigtable-column-family` for more information about
+See :doc:`column-family` for more information about
 :class:`GarbageCollectionRule <google.cloud.bigtable.column_family.GarbageCollectionRule>`
 and related classes.
 
@@ -141,7 +141,7 @@ Now we go down the final step of the hierarchy from
 :class:`Row <google.cloud.bigtable.row.Row>` as well as streaming
 data directly via a :class:`Table <google.cloud.bigtable.table.Table>`.
 
-Head next to learn about the :doc:`bigtable-data-api`.
+Head next to learn about the :doc:`data-api`.
 
 .. _ListTables: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/table/v1/bigtable_table_service.proto#L40-L42
 .. _CreateTable: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/table/v1/bigtable_table_service.proto#L35-L37

diff --git a/docs/bigtable-table.rst → docs/bigtable/table.rst b/docs/bigtable-table.rst → docs/bigtable/table.rst
diff --git a/docs/bigtable-usage.rst → docs/bigtable/usage.rst b/docs/bigtable-usage.rst → docs/bigtable/usage.rst
@@ -1,13 +1,30 @@
-Using the API
-=============
+Bigtable
+========
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  client-intro
+  client
+  cluster
+  instance
+  instance-api
+  table
+  table-api
+  column-family
+  row
+  row-data
+  row-filters
+  data-api
 
 API requests are sent to the `Google Cloud Bigtable`_ API via RPC over HTTP/2.
 In order to support this, we'll rely on `gRPC`_. We are working with the gRPC
 team to rapidly make the install story more user-friendly.
 
 Get started by learning about the
 :class:`Client <google.cloud.bigtable.client.Client>` on the
-:doc:`bigtable-client-intro` page.
+:doc:`client-intro` page.
 
 In the hierarchy of API concepts
 

diff --git a/docs/google-cloud-auth.rst → docs/core/auth.rst b/docs/google-cloud-auth.rst → docs/core/auth.rst
diff --git a/docs/google-cloud-config.rst → docs/core/config.rst b/docs/google-cloud-config.rst → docs/core/config.rst
@@ -43,7 +43,7 @@ Authentication
 ==============
 
 The authentication credentials can be implicitly determined from the
-environment or directly. See :doc:`google-cloud-auth`.
+environment or directly. See :doc:`/core/auth`.
 
 Logging in via ``gcloud beta auth application-default login`` will
 automatically configure a JSON key file with your default project ID and

diff --git a/docs/core/index.rst b/docs/core/index.rst
@@ -0,0 +1,10 @@
+Core
+====
+
+.. toctree::
+    config
+    auth
+    iterators
+    operation-api
+    modules
+
diff --git a/docs/iterators.rst → docs/core/iterators.rst b/docs/iterators.rst → docs/core/iterators.rst
diff --git a/docs/google-cloud-api.rst → docs/core/modules.rst b/docs/google-cloud-api.rst → docs/core/modules.rst
diff --git a/docs/operation-api.rst → docs/core/operation-api.rst b/docs/operation-api.rst → docs/core/operation-api.rst
diff --git a/docs/datastore-usage.rst b/docs/datastore-usage.rst
diff --git a/docs/datastore-batches.rst → docs/datastore/batches.rst b/docs/datastore-batches.rst → docs/datastore/batches.rst
diff --git a/docs/datastore-client.rst → docs/datastore/client.rst b/docs/datastore-client.rst → docs/datastore/client.rst
diff --git a/docs/datastore-entities.rst → docs/datastore/entities.rst b/docs/datastore-entities.rst → docs/datastore/entities.rst
diff --git a/docs/datastore-helpers.rst → docs/datastore/helpers.rst b/docs/datastore-helpers.rst → docs/datastore/helpers.rst
diff --git a/docs/datastore-keys.rst → docs/datastore/keys.rst b/docs/datastore-keys.rst → docs/datastore/keys.rst
diff --git a/docs/datastore-queries.rst → docs/datastore/queries.rst b/docs/datastore-queries.rst → docs/datastore/queries.rst
diff --git a/docs/datastore-transactions.rst → docs/datastore/transactions.rst b/docs/datastore-transactions.rst → docs/datastore/transactions.rst
diff --git a/docs/datastore/usage.rst b/docs/datastore/usage.rst
@@ -0,0 +1,21 @@
+Datastore
+=========
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  client
+  entities
+  keys
+  queries
+  transactions
+  batches
+  helpers
+
+Modules
+-------
+
+.. automodule:: google.cloud.datastore
+  :members:
+  :show-inheritance:
diff --git a/docs/dns-changes.rst → docs/dns/changes.rst b/docs/dns-changes.rst → docs/dns/changes.rst
diff --git a/docs/dns-client.rst → docs/dns/client.rst b/docs/dns-client.rst → docs/dns/client.rst
diff --git a/docs/dns-resource-record-set.rst → docs/dns/resource-record-set.rst b/docs/dns-resource-record-set.rst → docs/dns/resource-record-set.rst
diff --git a/docs/dns-usage.rst → docs/dns/usage.rst b/docs/dns-usage.rst → docs/dns/usage.rst
@@ -1,5 +1,14 @@
-Using the API
-=============
+DNS
+===
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  client
+  zone
+  resource-record-set
+  changes
 
 Client
 ------
@@ -8,7 +17,7 @@ Client
 configure your DNS applications.  Each instance holds both a ``project``
 and an authenticated connection to the DNS service.
 
-For an overview of authentication in ``google-cloud-python``, see :doc:`google-cloud-auth`.
+For an overview of authentication in ``google-cloud-python``, see :doc:`/core/auth`.
 
 Assuming your environment is set up as described in that document,
 create an instance of :class:`Client <google.cloud.dns.client.Client>`.

diff --git a/docs/dns-zone.rst → docs/dns/zone.rst b/docs/dns-zone.rst → docs/dns/zone.rst
diff --git a/docs/error-reporting-client.rst → docs/error-reporting/client.rst b/docs/error-reporting-client.rst → docs/error-reporting/client.rst
diff --git a/docs/error-reporting-usage.rst → docs/error-reporting/usage.rst b/docs/error-reporting-usage.rst → docs/error-reporting/usage.rst
@@ -1,12 +1,18 @@
-Using the API
-=============
+Stackdriver Error Reporting
+===========================
 
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  client
+  util
 
 Authentication and Configuration
 --------------------------------
 
 - For an overview of authentication in ``google-cloud-python``,
-  see :doc:`google-cloud-auth`.
+  see :doc:`/core/auth`.
 
 - In addition to any authentication configuration, you should also set the
   :envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the project you'd like

diff --git a/docs/error-reporting-util.rst → docs/error-reporting/util.rst b/docs/error-reporting-util.rst → docs/error-reporting/util.rst