Skip to content

Commit c2a7bff

Browse files
tseavertseaver
authored
Prep bigquery docs for repo split (googleapis#5955)
* Move 'docs/bigquery' to 'bigquery/docs' and leave symlink behind. * Rename BQ's 'usage.rst' -> 'index.rst'. * DRY 'bigquery/README.rst'<->'bigquery/docs/index.rst'. * Add Sphinx logic for managing static redirect files. Add a redirect for BigQuery from 'usage.html' -> 'index.html'. * Find snippets under 'bigquery/docs/'.
1 parent 64caa5f commit c2a7bff

File tree

14 files changed

+109
-106
lines changed

14 files changed

+109
-106
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ htmlcov
5151
# Built documentation
5252
docs/_build
5353
docs/_build_doc2dash
54+
bigquery/docs/generated
5455

5556
# Virtual environment
5657
env/

‎bigquery/README.rst‎

Lines changed: 54 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,76 @@
11
Python Client for Google BigQuery
22
=================================
33

4-
Python idiomatic client for `Google BigQuery`_
5-
6-
.. _Google BigQuery: https://cloud.google.com/bigquery/what-is-bigquery
7-
84
|pypi| |versions|
95

10-
- `Documentation`_
6+
Querying massive datasets can be time consuming and expensive without the
7+
right hardware and infrastructure. Google `BigQuery`_ solves this problem by
8+
enabling super-fast, SQL queries against append-mostly tables, using the
9+
processing power of Google's infrastructure.
1110

12-
.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/usage.html
11+
- `Client Library Documentation`_
12+
- `Product Documentation`_
13+
14+
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigquery.svg
15+
:target: https://pypi.org/project/google-cloud-bigquery/
16+
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigquery.svg
17+
:target: https://pypi.org/project/google-cloud-bigquery/
18+
.. _BigQuery: https://cloud.google.com/bigquery/what-is-bigquery
19+
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/index.html
20+
.. _Product Documentation: https://cloud.google.com/bigquery/docs/reference/v2/
1321

1422
Quick Start
1523
-----------
1624

17-
.. code-block:: console
25+
In order to use this library, you first need to go through the following steps:
1826

19-
$ pip install --upgrade google-cloud-bigquery
27+
1. `Select or create a Cloud Platform project.`_
28+
2. `Enable billing for your project.`_
29+
3. `Enable the Google Cloud Datastore API.`_
30+
4. `Setup Authentication.`_
2031

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.
32+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
33+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
34+
.. _Enable the Google Cloud Datastore API.: https://cloud.google.com/bigquery
35+
.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
2436

25-
.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
37+
Installation
38+
~~~~~~~~~~~~
2639

27-
Authentication
28-
--------------
40+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
41+
create isolated Python environments. The basic problem it addresses is one of
42+
dependencies and versions, and indirectly permissions.
2943

30-
With ``google-cloud-python`` we try to make authentication as painless as
31-
possible. Check out the `Authentication section`_ in our documentation to
32-
learn more. You may also find the `authentication document`_ shared by all
33-
the ``google-cloud-*`` libraries to be helpful.
44+
With `virtualenv`_, it's possible to install this library without needing system
45+
install permissions, and without clashing with the installed system
46+
dependencies.
3447

35-
.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
36-
.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
48+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
3749

38-
Using the API
39-
-------------
4050

41-
Querying massive datasets can be time consuming and expensive without the
42-
right hardware and infrastructure. Google `BigQuery`_ (`BigQuery API docs`_)
43-
solves this problem by enabling super-fast, SQL queries against
44-
append-mostly tables, using the processing power of Google's infrastructure.
51+
Mac/Linux
52+
^^^^^^^^^
4553

46-
.. _BigQuery: https://cloud.google.com/bigquery/what-is-bigquery
47-
.. _BigQuery API docs: https://cloud.google.com/bigquery/docs/reference/v2/
54+
.. code-block:: console
55+
56+
pip install virtualenv
57+
virtualenv <your-env>
58+
source <your-env>/bin/activate
59+
<your-env>/bin/pip install google-cloud-bigquery
60+
61+
62+
Windows
63+
^^^^^^^
64+
65+
.. code-block:: console
66+
67+
pip install virtualenv
68+
virtualenv <your-env>
69+
<your-env>\Scripts\activate
70+
<your-env>\Scripts\pip.exe install google-cloud-bigquery
71+
72+
Example Usage
73+
-------------
4874

4975
Create a dataset
5076
~~~~~~~~~~~~~~~~
@@ -106,14 +132,3 @@ Perform a query
106132
107133
for row in rows:
108134
print(row.name)
109-
110-
111-
See the ``google-cloud-python`` API `BigQuery documentation`_ to learn how
112-
to connect to BigQuery using this Client Library.
113-
114-
.. _BigQuery documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/usage.html
115-
116-
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigquery.svg
117-
:target: https://pypi.org/project/google-cloud-bigquery/
118-
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigquery.svg
119-
:target: https://pypi.org/project/google-cloud-bigquery/

docs/bigquery/.gitignore renamed to bigquery/docs/.gitignore

File renamed without changes.

‎bigquery/docs/changelog.md‎

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

docs/bigquery/dbapi.rst renamed to bigquery/docs/dbapi.rst

File renamed without changes.

docs/bigquery/usage.rst renamed to bigquery/docs/index.rst

Lines changed: 22 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,7 @@
1-
BigQuery
2-
========
3-
4-
.. toctree::
5-
:maxdepth: 2
6-
:hidden:
7-
8-
reference
9-
dbapi
10-
11-
.. contents:: :local:
12-
13-
Installation
14-
------------
15-
16-
Install the ``google-cloud-bigquery`` library using ``pip``:
17-
18-
.. code-block:: console
19-
20-
$ pip install google-cloud-bigquery
21-
22-
.. note::
23-
24-
This library changed significantly before the 1.0.0 release, especially
25-
between version 0.27 and 0.28. See `Migrating from the BigQuery Python
26-
client library version 0.27
27-
<https://cloud.google.com/bigquery/docs/python-client-migration>`__ for
28-
instructions on how to migrated your code to the most recent version of
29-
this library.
30-
31-
Authentication / Configuration
32-
------------------------------
33-
34-
- Use :class:`Client <google.cloud.bigquery.client.Client>` objects to configure
35-
your applications.
36-
37-
- :class:`Client <google.cloud.bigquery.client.Client>` objects hold both a ``project``
38-
and an authenticated connection to the BigQuery service.
39-
40-
- The authentication credentials can be implicitly determined from the
41-
environment or directly via
42-
:meth:`from_service_account_json <google.cloud.bigquery.client.Client.from_service_account_json>`
43-
and
44-
:meth:`from_service_account_p12 <google.cloud.bigquery.client.Client.from_service_account_p12>`.
45-
46-
- After setting :envvar:`GOOGLE_APPLICATION_CREDENTIALS` and
47-
:envvar:`GOOGLE_CLOUD_PROJECT` environment variables, create an instance of
48-
:class:`Client <google.cloud.bigquery.client.Client>`.
49-
50-
.. code-block:: python
51-
52-
>>> from google.cloud import bigquery
53-
>>> client = bigquery.Client()
1+
.. include:: /../bigquery/README.rst
542

3+
Using the Library
4+
=================
555

566
Projects
577
--------
@@ -68,8 +18,8 @@ To override the project inferred from the environment, pass an explicit
6818

6919
.. code-block:: python
7020
71-
>>> from google.cloud import bigquery
72-
>>> client = bigquery.Client(project='PROJECT_ID')
21+
from google.cloud import bigquery
22+
client = bigquery.Client(project='PROJECT_ID')
7323
7424
7525
Project ACLs
@@ -155,7 +105,7 @@ Tables exist within datasets. See BigQuery documentation for more information
155105
on `Tables <https://cloud.google.com/bigquery/docs/tables>`_.
156106

157107
Table operations
158-
~~~~~~~~~~~~~~~~~~
108+
~~~~~~~~~~~~~~~~
159109
List tables for the dataset:
160110

161111
.. literalinclude:: snippets.py
@@ -237,7 +187,7 @@ Upload table data from a file:
237187
:end-before: [END bigquery_load_from_file]
238188

239189
Load table data from Google Cloud Storage
240-
*****************************************
190+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
241191

242192
See also: `Loading JSON data from Cloud Storage
243193
<https://cloud.google.com/bigquery/docs/loading-data-cloud-storage-json>`_.
@@ -324,7 +274,7 @@ Queries
324274

325275

326276
Querying data
327-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
277+
~~~~~~~~~~~~~
328278

329279
Run a query and wait for it to finish:
330280

@@ -371,8 +321,11 @@ See BigQuery documentation for more information on
371321
:end-before: [END bigquery_query_params_named]
372322

373323

324+
Jobs
325+
----
326+
374327
List jobs for a project
375-
-----------------------
328+
~~~~~~~~~~~~~~~~~~~~~~~
376329

377330
Jobs describe actions performed on data in BigQuery tables:
378331

@@ -451,8 +404,17 @@ and load it into a new table:
451404
:start-after: [START bigquery_load_table_dataframe]
452405
:end-before: [END bigquery_load_table_dataframe]
453406

407+
API Reference
408+
=============
409+
410+
.. toctree::
411+
:maxdepth: 2
412+
413+
reference
414+
dbapi
415+
454416
Changelog
455-
---------
417+
=========
456418

457419
For a list of all ``google-cloud-bigquery`` releases:
458420

docs/bigquery/reference.rst renamed to bigquery/docs/reference.rst

File renamed without changes.

docs/bigquery/snippets.py renamed to bigquery/docs/snippets.py

File renamed without changes.

‎bigquery/docs/usage.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<html>
2+
<head>
3+
<meta http-equiv="refresh" content="1; url=./index.html:" />
4+
<script>
5+
window.location.href = "./index.html"
6+
</script>
7+
</head>
8+
</html>

‎bigquery/nox.py‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -147,10 +147,7 @@ def snippets(session, py):
147147

148148
# Run py.test against the system tests.
149149
session.run(
150-
'py.test',
151-
os.path.join(os.pardir, 'docs', 'bigquery', 'snippets.py'),
152-
*session.posargs
153-
)
150+
'py.test', os.path.join('docs', 'snippets.py'), *session.posargs)
154151

155152

156153
@nox.session
@@ -167,7 +164,7 @@ def lint(session):
167164
session.run('flake8', os.path.join('google', 'cloud', 'bigquery'))
168165
session.run('flake8', 'tests')
169166
session.run(
170-
'flake8', os.path.join(os.pardir, 'docs', 'bigquery', 'snippets.py'))
167+
'flake8', os.path.join('docs', 'snippets.py'))
171168

172169

173170
@nox.session

0 commit comments

Comments
 (0)