Skip to content
Permalink
Browse files
docs: update docs (#77)
- update branding
- remove docs for auto-generated library
  • Loading branch information
daniel-sanche committed Oct 27, 2020
1 parent bf579e4 commit bdd9c440f29d1fcd6fb9545d8465c63efa6c0cea
Showing with 76 additions and 101 deletions.
  1. +1 −1 CHANGELOG.md
  2. +5 −52 README.rst
  3. +14 −7 docs/conf.py
  4. +0 −6 docs/gapic/v2/api.rst
  5. +0 −5 docs/gapic/v2/types.rst
  6. +2 −2 docs/handlers-container-engine.rst
  7. +0 −1 docs/index.rst
  8. +1 −1 docs/snippets.py
  9. +3 −3 docs/usage.rst
  10. +0 −18 docs/v1.rst
  11. +13 −2 docs/v2.rst
  12. +35 −2 noxfile.py
  13. +2 −1 synth.py
@@ -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/
@@ -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.
@@ -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.

This file was deleted.

This file was deleted.

@@ -1,5 +1,5 @@
Google Container Engine Log Handler
===================================
Google Kubernetes Engine Log Handler
====================================

.. automodule:: google.cloud.logging.handlers.container_engine
:members:
@@ -5,7 +5,6 @@ Documentation
.. toctree::
:maxdepth: 3

v1
v2

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

This file was deleted.

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

0 comments on commit bdd9c44

Please sign in to comment.