From 679966cabe0a192ef3f84f973e891337ee5076a1 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 12 Sep 2018 11:51:28 -0400 Subject: [PATCH 1/5] Move 'docs/bigquery' to 'bigquery/docs' and leave symlink behind. --- .gitignore | 1 + {docs/bigquery => bigquery/docs}/.gitignore | 0 {docs/bigquery => bigquery/docs}/changelog.md | 0 {docs/bigquery => bigquery/docs}/dbapi.rst | 0 {docs/bigquery => bigquery/docs}/reference.rst | 0 {docs/bigquery => bigquery/docs}/snippets.py | 0 {docs/bigquery => bigquery/docs}/usage.rst | 0 docs/bigquery | 1 + 8 files changed, 2 insertions(+) rename {docs/bigquery => bigquery/docs}/.gitignore (100%) rename {docs/bigquery => bigquery/docs}/changelog.md (100%) rename {docs/bigquery => bigquery/docs}/dbapi.rst (100%) rename {docs/bigquery => bigquery/docs}/reference.rst (100%) rename {docs/bigquery => bigquery/docs}/snippets.py (100%) rename {docs/bigquery => bigquery/docs}/usage.rst (100%) create mode 120000 docs/bigquery diff --git a/.gitignore b/.gitignore index 295771ac79ae..a769e15e9823 100644 --- a/.gitignore +++ b/.gitignore @@ -51,6 +51,7 @@ htmlcov # Built documentation docs/_build docs/_build_doc2dash +bigquery/docs/generated # Virtual environment env/ diff --git a/docs/bigquery/.gitignore b/bigquery/docs/.gitignore similarity index 100% rename from docs/bigquery/.gitignore rename to bigquery/docs/.gitignore diff --git a/docs/bigquery/changelog.md b/bigquery/docs/changelog.md similarity index 100% rename from docs/bigquery/changelog.md rename to bigquery/docs/changelog.md diff --git a/docs/bigquery/dbapi.rst b/bigquery/docs/dbapi.rst similarity index 100% rename from docs/bigquery/dbapi.rst rename to bigquery/docs/dbapi.rst diff --git a/docs/bigquery/reference.rst b/bigquery/docs/reference.rst similarity index 100% rename from docs/bigquery/reference.rst rename to bigquery/docs/reference.rst diff --git a/docs/bigquery/snippets.py b/bigquery/docs/snippets.py similarity index 100% rename from docs/bigquery/snippets.py rename to bigquery/docs/snippets.py diff --git a/docs/bigquery/usage.rst b/bigquery/docs/usage.rst similarity index 100% rename from docs/bigquery/usage.rst rename to bigquery/docs/usage.rst diff --git a/docs/bigquery b/docs/bigquery new file mode 120000 index 000000000000..eb7d0e491992 --- /dev/null +++ b/docs/bigquery @@ -0,0 +1 @@ +../bigquery/docs/ \ No newline at end of file From 752e81d8ab9b324579995d01570901b16d735fda Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 12 Sep 2018 11:55:53 -0400 Subject: [PATCH 2/5] Rename BQ's 'usage.rst' -> 'index.rst'. --- bigquery/docs/{usage.rst => index.rst} | 0 docs/index.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename bigquery/docs/{usage.rst => index.rst} (100%) diff --git a/bigquery/docs/usage.rst b/bigquery/docs/index.rst similarity index 100% rename from bigquery/docs/usage.rst rename to bigquery/docs/index.rst diff --git a/docs/index.rst b/docs/index.rst index 577809c93cce..1e7560c3db26 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,7 +5,7 @@ Core Libraries Asset Management AutoML - BigQuery + BigQuery BigQuery Data-Transfer Bigtable Container From 1aa86f9619eb81dc5ee03eb6b83af9cfa7e95e9d Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 12 Sep 2018 12:27:06 -0400 Subject: [PATCH 3/5] DRY 'bigquery/README.rst'<->'bigquery/docs/index.rst'. --- bigquery/README.rst | 93 ++++++++++++++++++++++---------------- bigquery/docs/changelog.md | 2 +- bigquery/docs/index.rst | 82 +++++++++------------------------ 3 files changed, 77 insertions(+), 100 deletions(-) diff --git a/bigquery/README.rst b/bigquery/README.rst index 1a15304a1bef..7f9d2d8213e9 100644 --- a/bigquery/README.rst +++ b/bigquery/README.rst @@ -1,50 +1,76 @@ Python Client for Google BigQuery ================================= - Python idiomatic client for `Google BigQuery`_ - -.. _Google BigQuery: https://cloud.google.com/bigquery/what-is-bigquery - |pypi| |versions| -- `Documentation`_ +Querying massive datasets can be time consuming and expensive without the +right hardware and infrastructure. Google `BigQuery`_ solves this problem by +enabling super-fast, SQL queries against append-mostly tables, using the +processing power of Google's infrastructure. -.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/usage.html +- `Client Library Documentation`_ +- `Product Documentation`_ + +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigquery.svg + :target: https://pypi.org/project/google-cloud-bigquery/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigquery.svg + :target: https://pypi.org/project/google-cloud-bigquery/ +.. _BigQuery: https://cloud.google.com/bigquery/what-is-bigquery +.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/index.html +.. _Product Documentation: https://cloud.google.com/bigquery/docs/reference/v2/ Quick Start ----------- -.. code-block:: console +In order to use this library, you first need to go through the following steps: - $ pip install --upgrade google-cloud-bigquery +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Google Cloud Datastore API.`_ +4. `Setup Authentication.`_ -For more information on setting up your Python development environment, -such as installing ``pip`` and ``virtualenv`` on your system, please refer -to `Python Development Environment Setup Guide`_ for Google Cloud Platform. +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Google Cloud Datastore API.: https://cloud.google.com/bigquery +.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html -.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup +Installation +~~~~~~~~~~~~ -Authentication --------------- +Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to +create isolated Python environments. The basic problem it addresses is one of +dependencies and versions, and indirectly permissions. -With ``google-cloud-python`` we try to make authentication as painless as -possible. Check out the `Authentication section`_ in our documentation to -learn more. You may also find the `authentication document`_ shared by all -the ``google-cloud-*`` libraries to be helpful. +With `virtualenv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. -.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html -.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication +.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ -Using the API -------------- -Querying massive datasets can be time consuming and expensive without the -right hardware and infrastructure. Google `BigQuery`_ (`BigQuery API docs`_) -solves this problem by enabling super-fast, SQL queries against -append-mostly tables, using the processing power of Google's infrastructure. +Mac/Linux +^^^^^^^^^ -.. _BigQuery: https://cloud.google.com/bigquery/what-is-bigquery -.. _BigQuery API docs: https://cloud.google.com/bigquery/docs/reference/v2/ +.. code-block:: console + + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-bigquery + + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-bigquery + +Example Usage +------------- Create a dataset ~~~~~~~~~~~~~~~~ @@ -106,14 +132,3 @@ Perform a query for row in rows: print(row.name) - - -See the ``google-cloud-python`` API `BigQuery documentation`_ to learn how -to connect to BigQuery using this Client Library. - -.. _BigQuery documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/usage.html - -.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigquery.svg - :target: https://pypi.org/project/google-cloud-bigquery/ -.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigquery.svg - :target: https://pypi.org/project/google-cloud-bigquery/ diff --git a/bigquery/docs/changelog.md b/bigquery/docs/changelog.md index 857432bf6909..04c99a55caae 120000 --- a/bigquery/docs/changelog.md +++ b/bigquery/docs/changelog.md @@ -1 +1 @@ -../../bigquery/CHANGELOG.md \ No newline at end of file +../CHANGELOG.md \ No newline at end of file diff --git a/bigquery/docs/index.rst b/bigquery/docs/index.rst index 87edfd5e5556..94580556c862 100644 --- a/bigquery/docs/index.rst +++ b/bigquery/docs/index.rst @@ -1,57 +1,7 @@ -BigQuery -======== - -.. toctree:: - :maxdepth: 2 - :hidden: - - reference - dbapi - -.. contents:: :local: - -Installation ------------- - -Install the ``google-cloud-bigquery`` library using ``pip``: - -.. code-block:: console - - $ pip install google-cloud-bigquery - -.. note:: - - This library changed significantly before the 1.0.0 release, especially - between version 0.27 and 0.28. See `Migrating from the BigQuery Python - client library version 0.27 - `__ for - instructions on how to migrated your code to the most recent version of - this library. - -Authentication / Configuration ------------------------------- - -- Use :class:`Client ` objects to configure - your applications. - -- :class:`Client ` objects hold both a ``project`` - and an authenticated connection to the BigQuery service. - -- The authentication credentials can be implicitly determined from the - environment or directly via - :meth:`from_service_account_json ` - and - :meth:`from_service_account_p12 `. - -- After setting :envvar:`GOOGLE_APPLICATION_CREDENTIALS` and - :envvar:`GOOGLE_CLOUD_PROJECT` environment variables, create an instance of - :class:`Client `. - - .. code-block:: python - - >>> from google.cloud import bigquery - >>> client = bigquery.Client() +.. include:: /../bigquery/README.rst +Using the Library +================= Projects -------- @@ -68,8 +18,8 @@ To override the project inferred from the environment, pass an explicit .. code-block:: python - >>> from google.cloud import bigquery - >>> client = bigquery.Client(project='PROJECT_ID') + from google.cloud import bigquery + client = bigquery.Client(project='PROJECT_ID') Project ACLs @@ -155,7 +105,7 @@ Tables exist within datasets. See BigQuery documentation for more information on `Tables `_. Table operations -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ List tables for the dataset: .. literalinclude:: snippets.py @@ -237,7 +187,7 @@ Upload table data from a file: :end-before: [END bigquery_load_from_file] Load table data from Google Cloud Storage -***************************************** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See also: `Loading JSON data from Cloud Storage `_. @@ -324,7 +274,7 @@ Queries Querying data -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~ Run a query and wait for it to finish: @@ -371,8 +321,11 @@ See BigQuery documentation for more information on :end-before: [END bigquery_query_params_named] +Jobs +---- + List jobs for a project ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ Jobs describe actions performed on data in BigQuery tables: @@ -451,8 +404,17 @@ and load it into a new table: :start-after: [START bigquery_load_table_dataframe] :end-before: [END bigquery_load_table_dataframe] +API Reference +============= + +.. toctree:: + :maxdepth: 2 + + reference + dbapi + Changelog ---------- +========= For a list of all ``google-cloud-bigquery`` releases: From 1202113fa3a47053e416d1e3accb694975a9fac0 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 12 Sep 2018 17:08:29 -0400 Subject: [PATCH 4/5] Add Sphinx logic for managing static redirect files. Add a redirect for BigQuery from 'usage.html' -> 'index.html'. --- bigquery/docs/usage.html | 8 ++++++++ docs/conf.py | 19 +++++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 bigquery/docs/usage.html diff --git a/bigquery/docs/usage.html b/bigquery/docs/usage.html new file mode 100644 index 000000000000..9b81d6976cda --- /dev/null +++ b/bigquery/docs/usage.html @@ -0,0 +1,8 @@ + + + + + + diff --git a/docs/conf.py b/docs/conf.py index 2f6524fe9974..eee6ec7625e9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,6 +26,7 @@ import email import os import pkg_resources +import shutil # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -319,3 +320,21 @@ 'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None), 'python': ('https://docs.python.org/3', None), } + +# Static HTML pages, e.g. to support redirects +# See: https://tech.signavio.com/2017/managing-sphinx-redirects +# HTML pages to be copied from source to target +static_html_pages = [ + 'bigquery/usage.html', +] + +def copy_static_html_pages(app, docname): + if app.builder.name == 'html': + for static_html_page in static_html_pages: + target_path = app.outdir + '/' + static_html_page + src_path = app.srcdir + '/' + static_html_page + if os.path.isfile(src_path): + shutil.copyfile(src_path, target_path) + +def setup(app): + app.connect('build-finished', copy_static_html_pages) From 3a5414ab47fa95fc880f2b45407cf37b63c19eb6 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Thu, 13 Sep 2018 16:17:02 -0400 Subject: [PATCH 5/5] Find snippets under 'bigquery/docs/'. --- bigquery/nox.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/bigquery/nox.py b/bigquery/nox.py index a9d9242c55ac..902b6e663633 100644 --- a/bigquery/nox.py +++ b/bigquery/nox.py @@ -147,10 +147,7 @@ def snippets(session, py): # Run py.test against the system tests. session.run( - 'py.test', - os.path.join(os.pardir, 'docs', 'bigquery', 'snippets.py'), - *session.posargs - ) + 'py.test', os.path.join('docs', 'snippets.py'), *session.posargs) @nox.session @@ -167,7 +164,7 @@ def lint(session): session.run('flake8', os.path.join('google', 'cloud', 'bigquery')) session.run('flake8', 'tests') session.run( - 'flake8', os.path.join(os.pardir, 'docs', 'bigquery', 'snippets.py')) + 'flake8', os.path.join('docs', 'snippets.py')) @nox.session