googleapis · tseaver · Sep 12, 2018 · Sep 12, 2018
diff --git a/docs/index.rst b/docs/index.rst
@@ -26,7 +26,7 @@
  speech/index
  error-reporting/usage
  monitoring/index
-  logging/usage
+  logging/index
  redis/index
  storage/index
  tasks/index

diff --git a/docs/logging b/docs/logging
@@ -0,0 +1 @@
+../logging/docs/
diff --git a/docs/logging/changelog.md b/docs/logging/changelog.md
diff --git a/logging/CHANGELOG.md b/logging/CHANGELOG.md
@@ -44,20 +44,20 @@

 ## 1.5.0

-# New features
+### New features

 - Added `max_latency` to `BackgroundThreadTransport`. (#4762)
 - Added support for unique writer identity in `Sink`. (#4595, #4708, #4704, #4706)

-# Implementation changes
+### Implementation changes

 - The underlying auto-generated client library was re-generated to pick up new features and bugfixes. (#4759)
 - Moved the code path of `get_gae_labels()` to `emit()`. (#4824)
 - Removed a debug print statement. (#4838)
 - `LogSink.create` captures the server-generated `writerIdentity`. (#4707)
 - Accomodated a back-end change making `Sink.filter` optional. (#4699)

-# Testing
+### Testing

 - Fixed system tests (#4768)
 - Hardened test for `retrieve_metadata_server` against transparent DNS proxies. (#4698)
@@ -67,7 +67,7 @@
 - Maked a `nox -s default` session for all packages. (#4324)
 - Shortened test names. (#4321)

-# Documentation
+### Documentation

 - Added doc to highlight missing `uniqueWriterIdentity` field. (#4579)
 - Fixing "Fore" -> "For" typo in README docs. (#4317)

diff --git a/logging/README.rst b/logging/README.rst
@@ -1,51 +1,82 @@
 Python Client for Stackdriver Logging
 =====================================

-    Python idiomatic client for `Stackdriver Logging`_
-
-.. _Stackdriver Logging: https://cloud.google.com/logging/
-
 |pypi| |versions|

-  `Documentation`_
+`Stackdriver Logging API`_: Writes log entries and manages your Stackdriver
+Logging configuration.

-.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/logging/usage.html
+- `Client Library Documentation`_
+- `Product Documentation`_
+
+.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg
+   :target: https://pypi.org/project/google-cloud-logging/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg
+   :target: https://pypi.org/project/google-cloud-logging/
+.. _Stackdriver Logging API: https://cloud.google.com/logging
+.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/logging/usage.html
+.. _Product Documentation:  https://cloud.google.com/logging/docs

 Quick Start
 -----------

-.. code-block:: console
+In order to use this library, you first need to go through the following steps:
+
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Stackdriver Logging API.`_
+4. `Setup Authentication.`_
+
+.. _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 Stackdriver Logging API.:  https://cloud.google.com/logging
+.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
+
+Installation
+~~~~~~~~~~~~
+
+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 `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.

-    $ pip install --upgrade google-cloud-logging
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/

-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.

-.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
+Mac/Linux
+^^^^^^^^^

-**Note**: The creation of cross project sinks (log exports) is not currenlty supported. You may only create sinks within the same project set for the client. In other words, the parameter `uniqueWriterIdentity`_ is not yet available.
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    source <your-env>/bin/activate
+    <your-env>/bin/pip install google-cloud-logging

-.. _uniqueWriterIdentity: https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/create

-Authentication
--------------
+Windows
+^^^^^^^

-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.
+.. code-block:: console

-.. _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
+    pip install virtualenv
+    virtualenv <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\Scripts\pip.exe install google-cloud-logging

 Using the API
 -------------

-`Stackdriver Logging`_ API (`Logging API docs`_) allows you to store, search,
-analyze, monitor, and alert on log data and events from Google Cloud Platform.
+.. code:: python

-.. _Logging API docs: https://cloud.google.com/logging/docs/
+    from google.cloud import logging_v2
+
+    client = logging_v2.LoggingServiceV2Client()
+    entries = []
+    response = client.write_log_entries(entries)

 .. code:: python

@@ -58,15 +89,16 @@ Example of fetching entries:

 .. code:: python

+    from google.cloud import logging
+    client = logging.Client()
+    logger = client.logger('log_name')
    for entry in logger.list_entries():
        print(entry.payload)

-See the ``google-cloud-python`` API `logging documentation`_ to learn how to
-connect to Stackdriver Logging using this Client Library.
-
-.. _logging documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/logging/usage.html
+Next Steps
+~~~~~~~~~~

-.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg
-   :target: https://pypi.org/project/google-cloud-logging/
-.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg
-   :target: https://pypi.org/project/google-cloud-logging/
+-  Read the `Client Library Documentation`_ for 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/logging/docs/changelog.md b/logging/docs/changelog.md
@@ -0,0 +1 @@
+../CHANGELOG.md
diff --git a/docs/logging/client.rst → logging/docs/client.rst b/docs/logging/client.rst → logging/docs/client.rst
diff --git a/docs/logging/entries.rst → logging/docs/entries.rst b/docs/logging/entries.rst → logging/docs/entries.rst
diff --git a/logging/docs/gapic/v2/api.rst b/logging/docs/gapic/v2/api.rst
diff --git a/logging/docs/gapic/v2/types.rst b/logging/docs/gapic/v2/types.rst
diff --git a/docs/logging/handlers-app-engine.rst → logging/docs/handlers-app-engine.rst b/docs/logging/handlers-app-engine.rst → logging/docs/handlers-app-engine.rst
diff --git a/docs/logging/handlers-container-engine.rst → logging/docs/handlers-container-engine.rst b/docs/logging/handlers-container-engine.rst → logging/docs/handlers-container-engine.rst
diff --git a/docs/logging/handlers.rst → logging/docs/handlers.rst b/docs/logging/handlers.rst → logging/docs/handlers.rst
diff --git a/logging/docs/index.rst b/logging/docs/index.rst
@@ -1,99 +1,36 @@
-Python Client for Stackdriver Logging API (`Beta`_)
-===================================================
+.. include:: /../logging/README.rst

-`Stackdriver Logging API`_: Writes log entries and manages your Stackdriver Logging configuration.
-
- `Client Library Documentation`_
- `Product Documentation`_
-
-.. _Beta: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/README.rst
-.. _Stackdriver Logging API: https://cloud.google.com/logging
-.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/logging/usage.html
-.. _Product Documentation:  https://cloud.google.com/logging
-
-Quick Start
-----------
-
-In order to use this library, you first need to go through the following steps:
-
-1. `Select or create a Cloud Platform project.`_
-2. `Enable billing for your project.`_
-3. `Enable the Stackdriver Logging API.`_
-4. `Setup Authentication.`_
-
-.. _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 Stackdriver Logging API.:  https://cloud.google.com/logging
-.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
-
-Installation
-~~~~~~~~~~~~
-
-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 `virtualenv`_, it's possible to install this library without needing system
-install permissions, and without clashing with the installed system
-dependencies.
-
-.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
-
-
-Mac/Linux
-^^^^^^^^^
-
-.. code-block:: console
-
-    pip install virtualenv
-    virtualenv <your-env>
-    source <your-env>/bin/activate
-    <your-env>/bin/pip install google-cloud-logging
-
-
-Windows
-^^^^^^^
-
-.. code-block:: console
-
-    pip install virtualenv
-    virtualenv <your-env>
-    <your-env>\Scripts\activate
-    <your-env>\Scripts\pip.exe install google-cloud-logging
-
-Preview
-~~~~~~~
-
-LoggingServiceV2Client
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. code:: py
-
-    from google.cloud import logging_v2
-
-    client = logging_v2.LoggingServiceV2Client()
-
-    entries = []
-
-    response = client.write_log_entries(entries)
-
-Next Steps
-~~~~~~~~~~
-
-  Read the `Client Library Documentation`_ for Stackdriver Logging API
-   API to see other available methods on the client.
-  Read the `Stackdriver Logging API Product documentation`_ to learn
-   more about the product and see How-to Guides.
-  View this `repository’s main README`_ to see the full list of Cloud
-   APIs that we cover.
+Usage Documentation
+-------------------
+.. toctree::
+   :maxdepth: 2

-.. _Stackdriver Logging API Product documentation:  https://cloud.google.com/logging
-.. _repository’s main README: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/README.rst
+   usage

 Api Reference
 -------------
 .. toctree::
-    :maxdepth: 2
+   :maxdepth: 2
+
+   client
+   logger
+   entries
+   metric
+   sink
+   stdlib-usage
+   handlers
+   handlers-app-engine
+   handlers-container-engine
+   transports-sync
+   transports-thread
+   transports-base
+
+Changelog
+~~~~~~~~~
+
+For a list of all ``google-cloud-logging`` releases:
+
+.. toctree::
+   :maxdepth: 2

-    gapic/v2/api
-    gapic/v2/types
+   changelog
diff --git a/docs/logging/logger.rst → logging/docs/logger.rst b/docs/logging/logger.rst → logging/docs/logger.rst
diff --git a/docs/logging/metric.rst → logging/docs/metric.rst b/docs/logging/metric.rst → logging/docs/metric.rst
diff --git a/docs/logging/sink.rst → logging/docs/sink.rst b/docs/logging/sink.rst → logging/docs/sink.rst
diff --git a/docs/logging/snippets.py → logging/docs/snippets.py b/docs/logging/snippets.py → logging/docs/snippets.py
diff --git a/docs/logging/stdlib-usage.rst → logging/docs/stdlib-usage.rst b/docs/logging/stdlib-usage.rst → logging/docs/stdlib-usage.rst
diff --git a/docs/logging/transports-base.rst → logging/docs/transports-base.rst b/docs/logging/transports-base.rst → logging/docs/transports-base.rst
diff --git a/docs/logging/transports-sync.rst → logging/docs/transports-sync.rst b/docs/logging/transports-sync.rst → logging/docs/transports-sync.rst
diff --git a/docs/logging/transports-thread.rst → logging/docs/transports-thread.rst b/docs/logging/transports-thread.rst → logging/docs/transports-thread.rst