Skip to content

Commit 4eb4d90

Browse files
tseavertseaver
authored
Prep logging docs for repo split. (#5943)
- Move docs from 'docs/logging' into 'logging/docs' and leave symlink. - Harmonize / DRY 'logging/README.rst' and 'logging/docs/index.rst'. - Drop docs for GAPIC-generated helpers: they are not part of the surface. - Ensure that docs still build from top-level. Toward #5912.
1 parent b77a543 commit 4eb4d90

20 files changed

+991
-140
lines changed

‎packages/google-cloud-logging/CHANGELOG.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,20 +44,20 @@
4444

4545
## 1.5.0
4646

47-
# New features
47+
### New features
4848

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

52-
# Implementation changes
52+
### Implementation changes
5353

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

60-
# Testing
60+
### Testing
6161

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

70-
# Documentation
70+
### Documentation
7171

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

‎packages/google-cloud-logging/README.rst‎

Lines changed: 65 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,82 @@
11
Python Client for Stackdriver Logging
22
=====================================
33

4-
Python idiomatic client for `Stackdriver Logging`_
5-
6-
.. _Stackdriver Logging: https://cloud.google.com/logging/
7-
84
|pypi| |versions|
95

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

12-
.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/logging/usage.html
9+
- `Client Library Documentation`_
10+
- `Product Documentation`_
11+
12+
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg
13+
:target: https://pypi.org/project/google-cloud-logging/
14+
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg
15+
:target: https://pypi.org/project/google-cloud-logging/
16+
.. _Stackdriver Logging API: https://cloud.google.com/logging
17+
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/logging/usage.html
18+
.. _Product Documentation: https://cloud.google.com/logging/docs
1319

1420
Quick Start
1521
-----------
1622

17-
.. code-block:: console
23+
In order to use this library, you first need to go through the following steps:
24+
25+
1. `Select or create a Cloud Platform project.`_
26+
2. `Enable billing for your project.`_
27+
3. `Enable the Stackdriver Logging API.`_
28+
4. `Setup Authentication.`_
29+
30+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
31+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
32+
.. _Enable the Stackdriver Logging API.: https://cloud.google.com/logging
33+
.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
34+
35+
Installation
36+
~~~~~~~~~~~~
37+
38+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
39+
create isolated Python environments. The basic problem it addresses is one of
40+
dependencies and versions, and indirectly permissions.
41+
42+
With `virtualenv`_, it's possible to install this library without needing system
43+
install permissions, and without clashing with the installed system
44+
dependencies.
1845

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

21-
For more information on setting up your Python development environment,
22-
such as installing ``pip`` and ``virtualenv`` on your system, please refer
23-
to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
2448

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

27-
**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.
52+
.. code-block:: console
53+
54+
pip install virtualenv
55+
virtualenv <your-env>
56+
source <your-env>/bin/activate
57+
<your-env>/bin/pip install google-cloud-logging
2858
29-
.. _uniqueWriterIdentity: https://cloud.google.com/logging/docs/reference/v2/rest/v2/projects.sinks/create
3059
31-
Authentication
32-
--------------
60+
Windows
61+
^^^^^^^
3362

34-
With ``google-cloud-python`` we try to make authentication as painless as
35-
possible. Check out the `Authentication section`_ in our documentation to
36-
learn more. You may also find the `authentication document`_ shared by all
37-
the ``google-cloud-*`` libraries to be helpful.
63+
.. code-block:: console
3864
39-
.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
40-
.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
65+
pip install virtualenv
66+
virtualenv <your-env>
67+
<your-env>\Scripts\activate
68+
<your-env>\Scripts\pip.exe install google-cloud-logging
4169
4270
Using the API
4371
-------------
4472

45-
`Stackdriver Logging`_ API (`Logging API docs`_) allows you to store, search,
46-
analyze, monitor, and alert on log data and events from Google Cloud Platform.
73+
.. code:: python
4774
48-
.. _Logging API docs: https://cloud.google.com/logging/docs/
75+
from google.cloud import logging_v2
76+
77+
client = logging_v2.LoggingServiceV2Client()
78+
entries = []
79+
response = client.write_log_entries(entries)
4980
5081
.. code:: python
5182
@@ -58,15 +89,16 @@ Example of fetching entries:
5889

5990
.. code:: python
6091
92+
from google.cloud import logging
93+
client = logging.Client()
94+
logger = client.logger('log_name')
6195
for entry in logger.list_entries():
6296
print(entry.payload)
6397
64-
See the ``google-cloud-python`` API `logging documentation`_ to learn how to
65-
connect to Stackdriver Logging using this Client Library.
66-
67-
.. _logging documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/logging/usage.html
98+
Next Steps
99+
~~~~~~~~~~
68100

69-
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-logging.svg
70-
:target: https://pypi.org/project/google-cloud-logging/
71-
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-logging.svg
72-
:target: https://pypi.org/project/google-cloud-logging/
101+
- Read the `Client Library Documentation`_ for to see other available
102+
methods on the client.
103+
- Read the `Product documentation`_ to learn more about the product and see
104+
How-to Guides.

‎packages/google-cloud-logging/docs/changelog.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CHANGELOG.md

‎packages/google-cloud-logging/docs/client.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Stackdriver Logging Client
2+
==========================
3+
4+
.. automodule:: google.cloud.logging.client
5+
:members:
6+
:show-inheritance:

‎packages/google-cloud-logging/docs/entries.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Entries
2+
=======
3+
4+
.. automodule:: google.cloud.logging.entries
5+
:members:
6+
:show-inheritance:

‎packages/google-cloud-logging/docs/gapic/v2/api.rst‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎packages/google-cloud-logging/docs/gapic/v2/types.rst‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎packages/google-cloud-logging/docs/handlers-app-engine.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Google App Engine flexible Log Handler
2+
======================================
3+
4+
.. automodule:: google.cloud.logging.handlers.app_engine
5+
:members:
6+
:show-inheritance:

‎packages/google-cloud-logging/docs/handlers-container-engine.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Google Container Engine Log Handler
2+
===================================
3+
4+
.. automodule:: google.cloud.logging.handlers.container_engine
5+
:members:
6+
:show-inheritance:

‎packages/google-cloud-logging/docs/handlers.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Python Logging Module Handler
2+
==============================
3+
4+
.. automodule:: google.cloud.logging.handlers.handlers
5+
:members:
6+
:show-inheritance:

0 commit comments

Comments
 (0)