fix: improve docs

CHANGELOG.md

@@ -1,4 +1,5 @@
-# Changelog
+Changelog
+---------
 
 [PyPI History][1]
 
@@ -292,6 +293,6 @@
 - Upgrading to `google-cloud-core >= 0.28.0` and adding dependency
   on `google-api-core` (#4221, #4280)
 - Deferring to `google-api-core` for `grpcio` and
-  `googleapis-common-protos`dependencies (#4096, #4098)
+  `googleapis-common-protos` dependencies (#4096, #4098)
 
 PyPI: https://pypi.org/project/google-cloud-logging/1.4.0/

README.rst

@@ -1,9 +1,9 @@
-Python Client for Stackdriver Logging
+Python Client for Cloud Logging
 =====================================
 
 |pypi| |versions|
 
-`Stackdriver Logging API`_: Writes log entries and manages your Stackdriver
+`Cloud Logging API`_: Writes log entries and manages your Cloud
 Logging configuration.
 
 - `Client Library Documentation`_
@@ -13,9 +13,11 @@ Logging configuration.
    :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
+.. _Cloud Logging API: https://cloud.google.com/logging
 .. _Client Library Documentation: https://googleapis.dev/python/logging/latest
 .. _Product Documentation:  https://cloud.google.com/logging/docs
+.. _Setting Up Cloud Logging for Python: https://cloud.google.com/logging/docs/setup/python
+.. _Python's standard logging library: https://docs.python.org/2/library/logging.html
 
 Quick Start
 -----------
@@ -24,12 +26,12 @@ 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.`_
+3. `Enable the Cloud 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
+.. _Enable the Cloud Logging API.:  https://cloud.google.com/logging
 .. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
 
 Installation
@@ -77,57 +79,40 @@ Windows
 Using the API
 -------------
 
+Connecting Cloud Logging to `Python's standard logging library`_
+
 .. code:: python
 
-    from google.cloud import logging_v2
-    client = logging_v2.LoggingServiceV2Client()
-
-    resource = {
-        "type": "global",
-        "labels": {
-            "project_id": "[PROJECT_ID]"
-        }
-    }
-
-    """
-    Log entries can be either LogEntry or dict.
-    You can describe the same data in the following format:
-
-    e = {
-        "log_name": "projects/[PROJECT_ID]/logs/test-logging",
-        "resource": resource,
-        "text_payload": "this is a log statement",
-    }
-    """
-    e = logging_v2.types.LogEntry(
-        log_name="projects/[PROJECT_ID]/logs/test-logging", # optional
-        resource=resource, # optional
-        text_payload="this is a log statement")
-
-    entries = [e]
-    response = client.write_log_entries(entries)
+    # Imports the Cloud Logging client library
+    import google.cloud.logging
 
-.. code:: python
+    # Instantiates a client
+    client = google.cloud.logging.Client()
 
-    from google.cloud import logging
-    client = logging.Client()
-    logger = client.logger('log_name')
-    logger.log_text('A simple entry')  # API call
+    # Retrieves a Cloud Logging handler based on the environment
+    # you're running in and integrates the handler with the
+    # Python logging module. By default this captures all logs
+    # at INFO level and higher
+    client.setup_logging()
 
-Example of fetching entries:
+Using the Python root logger:
 
 .. code:: python
 
-    from google.cloud import logging
-    client = logging.Client()
-    logger = client.logger('log_name')
-    for entry in logger.list_entries():
-        print(entry.payload)
+    # Imports Python standard logging library
+    import logging
+
+    # The data to log
+    text = 'Hello, world!'
+
+    # Emits the data using the standard logging module
+    logging.warning(text)
 
 Next Steps
 ~~~~~~~~~~
 
+-  Read the `Setting Up Cloud Logging for Python`_ How-to Guide
+-  Read the `Product documentation`_ to learn more about the product and see other
+   How-to Guides.
 -  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.

docs/client.rst

@@ -1,4 +1,4 @@
-Stackdriver Logging Client
+Cloud Logging Client
 ==========================
 
 .. automodule:: google.cloud.logging.client

docs/conf.py

@@ -20,12 +20,16 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(".."))
 
+# For plugins that can not read conf.py.
+# See also: https://github.com/docascode/sphinx-docfx-yaml/issues/85
+sys.path.insert(0, os.path.abspath("."))
+
 __version__ = ""
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "1.6.3"
+needs_sphinx = "1.5.5"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -35,24 +39,22 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "recommonmark",
 ]
 
 # autodoc/autosummary flags
 autoclass_content = "both"
-autodoc_default_flags = ["members"]
+autodoc_default_options = {"members": True}
 autosummary_generate = True
 
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# Allow markdown includes (so releases.md can include CHANGLEOG.md)
-# http://www.sphinx-doc.org/en/master/markdown.html
-source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
-
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
@@ -93,7 +95,12 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = [
+    "_build",
+    "samples/AUTHORING_GUIDE.md",
+    "samples/CONTRIBUTING.md",
+    "samples/snippets/README.rst",
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

docs/handlers-container-engine.rst

@@ -1,5 +1,5 @@
-Google Container Engine Log Handler
-===================================
+Google Kubernetes Engine Log Handler
+====================================
 
 .. automodule:: google.cloud.logging.handlers.container_engine
   :members:

docs/index.rst

@@ -5,7 +5,6 @@ Documentation
 .. toctree::
    :maxdepth: 3
 
-   v1
    v2
 
 Changelog

docs/snippets.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Testable usage examples for Stackdriver Logging API wrapper
+"""Testable usage examples for Cloud Logging API wrapper
 
 Each example function takes a ``client`` argument (which must be an instance
 of :class:`google.cloud.logging.client.Client`) and uses it to perform a task

docs/usage.rst

@@ -112,7 +112,7 @@ Manage log metrics
 ------------------
 
 Metrics are counters of entries which match a given filter.  They can be
-used within Stackdriver Monitoring to create charts and alerts.
+used within Cloud Monitoring to create charts and alerts.
 
 List all metrics for a project:
 
@@ -259,7 +259,7 @@ Integration with Python logging module
 --------------------------------------
 
 It's possible to tie the Python :mod:`logging` module directly into Google
-Stackdriver Logging. There are different handler options to accomplish this.
+Cloud Logging. There are different handler options to accomplish this.
 To automatically pick the default for your current environment, use
 :meth:`~google.cloud.logging.client.Client.get_default_handler`.
 
@@ -269,7 +269,7 @@ To automatically pick the default for your current environment, use
     :dedent: 4
 
 It is also possible to attach the handler to the root Python logger, so that
-for example a plain ``logging.warn`` call would be sent to Stackdriver Logging,
+for example a plain ``logging.warn`` call would be sent to Cloud Logging,
 as well as any other loggers created. A helper method
 :meth:`~google.cloud.logging.client.Client.setup_logging` is provided
 to configure this automatically.
@@ -281,7 +281,7 @@ to configure this automatically.
 
 .. note::
 
-    To reduce cost and quota usage, do not enable Stackdriver logging
+    To reduce cost and quota usage, do not enable Cloud Logging
     handlers while testing locally.
 
 You can also exclude certain loggers:
@@ -336,7 +336,7 @@ logging handler can use different transports. The default is
     direct API call on each logging statement to write the entry.
 
 
-.. _Google Container Engine: https://cloud.google.com/container-engine/
+.. _Google Kubernetes Engine: https://cloud.google.com/kubernetes-engine
 
 fluentd logging handlers
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -347,15 +347,15 @@ which writes directly to the API, two other handlers are provided.
 recommended when running on the Google App Engine Flexible vanilla runtimes
 (i.e. your app.yaml contains ``runtime: python``), and
 :class:`~google.cloud.logging.handlers.container_engine.ContainerEngineHandler`
-, which is recommended when running on `Google Container Engine`_ with the
-Stackdriver Logging plugin enabled.
+, which is recommended when running on `Google Kubernetes Engine`_ with the
+Cloud Logging plugin enabled.
 
 :meth:`~google.cloud.logging.client.Client.get_default_handler` and
 :meth:`~google.cloud.logging.client.Client.setup_logging` will attempt to use
 the environment to automatically detect whether the code is running in
 these platforms and use the appropriate handler.
 
 In both cases, the fluentd agent is configured to automatically parse log files
-in an expected format and forward them to Stackdriver logging. The handlers
+in an expected format and forward them to Cloud Logging. The handlers
 provided help set the correct metadata such as log level so that logs can be
 filtered accordingly.

docs/v2.rst

@@ -3,5 +3,16 @@ v2
 .. toctree::
    :maxdepth: 2
 
-   gapic/v2/api
-   gapic/v2/types
+   usage
+   client
+   logger
+   entries
+   metric
+   sink
+   stdlib-usage
+   handlers
+   handlers-app-engine
+   handlers-container-engine
+   transports-sync
+   transports-thread
+   transports-base

noxfile.py

@@ -164,15 +164,48 @@ def cover(session):
 def docs(session):
     """Build the docs for this library."""
 
+    session.install('-e', '.')
+    session.install('sphinx', 'alabaster', 'recommonmark')
+
+    shutil.rmtree(os.path.join('docs', '_build'), ignore_errors=True)
+    session.run(
+        'sphinx-build',
+        '-W',  # warnings as errors
+        '-T',  # show full traceback on exception
+        '-N',  # no colors
+        '-b', 'html',
+        '-d', os.path.join('docs', '_build', 'doctrees', ''),
+        os.path.join('docs', ''),
+        os.path.join('docs', '_build', 'html', ''),
+    )
+
+
+@nox.session(python="3.7")
+def docfx(session):
+    """Build the docfx yaml files for this library."""
+
     session.install("-e", ".")
-    session.install("sphinx<3.0.0", "alabaster", "recommonmark")
+    # sphinx-docfx-yaml supports up to sphinx version 1.5.5.
+    # https://github.com/docascode/sphinx-docfx-yaml/issues/97
+    session.install("sphinx==1.5.5", "alabaster", "recommonmark", "sphinx-docfx-yaml")
 
     shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)
     session.run(
         "sphinx-build",
-        "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
+        "-D",
+        (
+            "extensions=sphinx.ext.autodoc,"
+            "sphinx.ext.autosummary,"
+            "docfx_yaml.extension,"
+            "sphinx.ext.intersphinx,"
+            "sphinx.ext.coverage,"
+            "sphinx.ext.napoleon,"
+            "sphinx.ext.todo,"
+            "sphinx.ext.viewcode,"
+            "recommonmark"
+        ),
         "-b",
         "html",
         "-d",