Skip to content

docs: clean up docs and let the nox pass #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 25, 2024
Merged

docs: clean up docs and let the nox pass #24

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7e64fb0
docs: clean up docs and let the nox pass
ashleyxuu Apr 17, 2024
b8d9bd9
update the commit
ashleyxuu Apr 17, 2024
2ca9c90
clean up the README.rst to pass lint_setup_py
ashleyxuu Apr 19, 2024
652a019
Trigger Build
ashleyxuu Apr 19, 2024
5df368a
address comments
ashleyxuu Apr 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 4 additions & 60 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
Python Client for Google BigQuery
IPython Magics for BigQuery

=================================

|GA| |pypi| |versions|
Expand Down Expand Up @@ -70,7 +71,7 @@ Mac/Linux
pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install google-cloud-bigquery
<your-env>/bin/pip install google-cloud-bigquery-magics


Windows
Expand All @@ -81,61 +82,4 @@ Windows
pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install google-cloud-bigquery

Example Usage
-------------

Perform a query
~~~~~~~~~~~~~~~

.. code:: python

from google.cloud import bigquery

client = bigquery.Client()

# Perform a query.
QUERY = (
'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` '
'WHERE state = "TX" '
'LIMIT 100')
query_job = client.query(QUERY) # API request
rows = query_job.result() # Waits for query to finish

for row in rows:
print(row.name)

Instrumenting With OpenTelemetry
--------------------------------

This application uses `OpenTelemetry`_ to output tracing data from
API calls to BigQuery. To enable OpenTelemetry tracing in
the BigQuery client the following PyPI packages need to be installed:

.. _OpenTelemetry: https://opentelemetry.io

.. code-block:: console

pip install google-cloud-bigquery[opentelemetry] opentelemetry-exporter-gcp-trace

After installation, OpenTelemetry can be used in the BigQuery
client and in BigQuery jobs. First, however, an exporter must be
specified for where the trace data will be outputted to. An
example of this can be found here:

.. code-block:: python

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
tracer_provider = TracerProvider()
tracer_provider = BatchSpanProcessor(CloudTraceSpanExporter())
trace.set_tracer_provider(TracerProvider())

In this example all tracing data will be published to the Google
`Cloud Trace`_ console. For more information on OpenTelemetry, please consult the `OpenTelemetry documentation`_.

.. _OpenTelemetry documentation: https://opentelemetry-python.readthedocs.io
.. _Cloud Trace: https://cloud.google.com/trace
<your-env>\Scripts\pip.exe install google-cloud-bigquery-magics
2 changes: 0 additions & 2 deletions docs/bigquery/legacy_proto_types.rst
View file
Open in desktop
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can delete this file. Probably in the next PR though, since it'll be nice just to have the docs build passing.

Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@ Legacy proto-based Types for Google Cloud Bigquery v2 API
anymore. They might also differ from the types uspported on the backend. It is
therefore strongly advised to migrate to the types found in :doc:`standard_sql`.

Also see the :doc:`3.0.0 Migration Guide<../UPGRADING>` for more information.

.. automodule:: google.cloud.bigquery_v2.types
:members:
:undoc-members:
Expand Down
4 changes: 2 additions & 2 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ More Examples
.. toctree::
:maxdepth: 2

usage/index
Official Google BigQuery How-to Guides <https://cloud.google.com/bigquery/docs/how-to>
magics
Official Google BigQuery Magics Guide <https://cloud.google.com/python/docs/reference/bigquery/latest/magics>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page is going to change. Likely we'll want to publish sphinx docs to googleapis.dev similar to https://googleapis.dev/python/pandas-gbq/latest/

That said, if you're looking for an equivalent to the usage guides, that's not it anyway.

https://cloud.google.com/bigquery/docs/visualize-jupyter is close, though that's a tutorial, not a usage guide.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK, putting https://cloud.google.com/bigquery/docs/visualize-jupyter link for interim now until we have the sphinx docs ready.


API Reference
-------------
Expand Down
4 changes: 2 additions & 2 deletions docs/magics.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@ Code Samples

Running a query:

.. literalinclude:: ./samples/snippets/query.py
.. literalinclude:: ../samples/snippets/query.py
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this actually work? In the past, I've had to put a symlink in the docs folder to the samples for the docs build to actually find the right files.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it works. Otherwise, I can't pass the nox -s docs

:dedent: 4
:start-after: [START bigquery_jupyter_query]
:end-before: [END bigquery_jupyter_query]

Running a parameterized query:

.. literalinclude:: ./samples/snippets/query_params_scalars.py
.. literalinclude:: ../samples/snippets/query_params_scalars.py
:dedent: 4
:start-after: [START bigquery_jupyter_query_params_scalars]
:end-before: [END bigquery_jupyter_query_params_scalars]
Expand Down
25 changes: 0 additions & 25 deletions docs/usage/client.rst
View file
Open in desktop

This file was deleted.

131 changes: 0 additions & 131 deletions docs/usage/datasets.rst
View file
Open in desktop

This file was deleted.

52 changes: 0 additions & 52 deletions docs/usage/encryption.rst
View file
Open in desktop

This file was deleted.

35 changes: 0 additions & 35 deletions docs/usage/index.rst
View file
Open in desktop

This file was deleted.

21 changes: 0 additions & 21 deletions docs/usage/jobs.rst
View file
Open in desktop

This file was deleted.

Loading