docs: update docs (googleapis#77)

- update branding
- remove docs for auto-generated library

Author: daniel-sanche

CHANGELOG.md

@@ -292,6 +292,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

@@ -16,6 +16,8 @@ Logging configuration.
 .. _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
 -----------
@@ -74,60 +76,11 @@ Windows
     <your-env>\Scripts\activate
     <your-env>\Scripts\pip.exe install google-cloud-logging
 
-Using the API
--------------
-
-.. 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)
-
-.. code:: python
-
-    from google.cloud import logging
-    client = logging.Client()
-    logger = client.logger('log_name')
-    logger.log_text('A simple entry')  # API call
-
-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)
-
 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/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/gapic/v2/api.rst

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

docs/gapic/v2/types.rst

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

docs/handlers-container-engine.rst

@@ -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/index.rst

@@ -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,7 +347,7 @@ 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
+, 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
@@ -356,6 +356,6 @@ 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 Cloud 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/snippets.py

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

docs/usage.rst

@@ -152,15 +152,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",

docs/v1.rst

@@ -34,7 +34,8 @@
 
 s.move(library / "google/cloud/logging_v2/gapic")
 s.move(library / "tests/unit/gapic/v2")
-s.move(library / "docs/gapic/v2")
+# Don't include gapic library docs. Users should use the hand-written layer instead
+# s.move(library / "docs/gapic/v2")
 
 # ----------------------------------------------------------------------------
 # Add templated files