diff --git a/CHANGELOG.md b/CHANGELOG.md index 2dfcc2eb..d0af80e6 100644 --- a/CHANGELOG.md +++ b/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/ diff --git a/README.rst b/README.rst index 68c04029..a81f28e8 100644 --- a/README.rst +++ b/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 \Scripts\activate \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. diff --git a/docs/conf.py b/docs/conf.py index 7a03936b..b507b408 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/gapic/v2/api.rst b/docs/gapic/v2/api.rst deleted file mode 100644 index 2dc6bf6f..00000000 --- a/docs/gapic/v2/api.rst +++ /dev/null @@ -1,6 +0,0 @@ -Client for Stackdriver Logging API -================================== - -.. automodule:: google.cloud.logging_v2 - :members: - :inherited-members: \ No newline at end of file diff --git a/docs/gapic/v2/types.rst b/docs/gapic/v2/types.rst deleted file mode 100644 index 5521d4f9..00000000 --- a/docs/gapic/v2/types.rst +++ /dev/null @@ -1,5 +0,0 @@ -Types for Stackdriver Logging API Client -======================================== - -.. automodule:: google.cloud.logging_v2.types - :members: \ No newline at end of file diff --git a/docs/handlers-container-engine.rst b/docs/handlers-container-engine.rst index a0c6b2bc..5286ec58 100644 --- a/docs/handlers-container-engine.rst +++ b/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: diff --git a/docs/index.rst b/docs/index.rst index f617201a..347dc9f8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,6 @@ Documentation .. toctree:: :maxdepth: 3 - v1 v2 Changelog diff --git a/docs/snippets.py b/docs/snippets.py index 77832798..7a862134 100644 --- a/docs/snippets.py +++ b/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 diff --git a/docs/usage.rst b/docs/usage.rst index dccec49e..4714144f 100644 --- a/docs/usage.rst +++ b/docs/usage.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. diff --git a/docs/v1.rst b/docs/v1.rst deleted file mode 100644 index f4f79d37..00000000 --- a/docs/v1.rst +++ /dev/null @@ -1,18 +0,0 @@ -v1 -============== -.. toctree:: - :maxdepth: 2 - - usage - client - logger - entries - metric - sink - stdlib-usage - handlers - handlers-app-engine - handlers-container-engine - transports-sync - transports-thread - transports-base \ No newline at end of file diff --git a/docs/v2.rst b/docs/v2.rst index 8dfc18b4..567eabd7 100644 --- a/docs/v2.rst +++ b/docs/v2.rst @@ -3,5 +3,16 @@ v2 .. toctree:: :maxdepth: 2 - gapic/v2/api - gapic/v2/types \ No newline at end of file + usage + client + logger + entries + metric + sink + stdlib-usage + handlers + handlers-app-engine + handlers-container-engine + transports-sync + transports-thread + transports-base diff --git a/noxfile.py b/noxfile.py index 2c976b6a..c55ecf87 100644 --- a/noxfile.py +++ b/noxfile.py @@ -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", diff --git a/synth.py b/synth.py index ee1b168a..9504c980 100644 --- a/synth.py +++ b/synth.py @@ -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