docs: build documentation with Sphinx

README.rst

@@ -1,12 +1,88 @@
-SQLAlchemy dialect and API client for BigQuery.
+SQLAlchemy Dialect for BigQuery
+===============================
 
+|beta| |pypi| |versions|
 
-Usage
-=====
+`SQLALchemy Dialects`_
+
+- `Dialect Documentation`_
+- `Product Documentation`_
+
+.. |beta| image:: https://img.shields.io/badge/support-beta-orange.svg
+   :target: https://github.com/googleapis/google-cloud-python/blob/master/README.rst#beta-support
+.. |pypi| image:: https://img.shields.io/pypi/v/pybigquery.svg
+   :target: https://pypi.org/project/pybigquery/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/pybigquery.svg
+   :target: https://pypi.org/project/pybigquery/
+.. _SQLAlchemy Dialects: https://docs.sqlalchemy.org/en/14/dialects/
+.. _Dialect Documentation: https://googleapis.dev/python/pybigquery/latest
+.. _Product Documentation: https://cloud.google.com/bigquery/docs/
+
+
+Quick Start
+-----------
+
+In order to use this library, you first need to go through the following steps:
+
+1. `Select or create a Cloud Platform project.`_
+2. [Optional] `Enable billing for your project.`_
+3. `Enable the BigQuery Storage API.`_
+4. `Setup Authentication.`_
+
+.. _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 BigQuery Storage API.: https://console.cloud.google.com/apis/library/bigquery.googleapis.com
+.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
+
+Installation
+------------
+
+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 `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
+
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
+
+
+Supported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Python >= 3.6
+
+Unsupported Python Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Python == 2.7, Python == 3.5.
+
+
+Mac/Linux
+^^^^^^^^^
+
+.. code-block:: console
 
+    pip install virtualenv
+    virtualenv <your-env>
+    source <your-env>/bin/activate
+    <your-env>/bin/pip install pybigquery
+
+
+Windows
+^^^^^^^
+
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\Scripts\pip.exe install pybigquery
+
+Usage
+-----
 
 SQLAlchemy
-__________
+^^^^^^^^^^
 
 .. code-block:: python
 
@@ -18,7 +94,7 @@ __________
     print(select([func.count('*')], from_obj=table).scalar())
 
 API Client
-__________
+^^^^^^^^^^
 
 .. code-block:: python
 
@@ -27,12 +103,12 @@ __________
     print(api_client.dry_run_query(query=sqlstr).total_bytes_processed)
 
 Project
-_______
+^^^^^^^
 
 ``project`` in ``bigquery://project`` is used to instantiate BigQuery client with the specific project ID. To infer project from the environment, use ``bigquery://`` – without ``project``
 
 Authentication
-______________
+^^^^^^^^^^^^^^
 
 Follow the `Google Cloud library guide <https://google-cloud-python.readthedocs.io/en/latest/core/auth.html>`_ for authentication. Alternatively, you can provide the path to a service account JSON file in ``create_engine()``:
 
@@ -42,7 +118,7 @@ Follow the `Google Cloud library guide <https://google-cloud-python.readthedocs.
 
 
 Location
-________
+^^^^^^^^
 
 To specify location of your datasets pass ``location`` to ``create_engine()``:
 
@@ -52,7 +128,7 @@ To specify location of your datasets pass ``location`` to ``create_engine()``:
 
 
 Table names
-___________
+^^^^^^^^^^^
 
 To query tables from non-default projects or datasets, use the following format for the SQLAlchemy schema name: ``[project.]dataset``, e.g.:
 
@@ -64,7 +140,7 @@ To query tables from non-default projects or datasets, use the following format
     sample_table_2 = Table('natality', schema='bigquery-public-data')
 
 Batch size
-__________
+^^^^^^^^^^
 
 By default, ``arraysize`` is set to ``5000``. ``arraysize`` is used to set the batch size for fetching results. To change it, pass ``arraysize`` to ``create_engine()``:
 
@@ -74,7 +150,7 @@ By default, ``arraysize`` is set to ``5000``. ``arraysize`` is used to set the b
 
 
 Adding a Default Dataset
-________________________
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you want to have the ``Client`` use a default dataset, specify it as the "database" portion of the connection string.
 
@@ -100,7 +176,7 @@ Note that specifying a default dataset doesn't restrict execution of queries to
 
 
 Connection String Parameters
-____________________________
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are many situations where you can't call ``create_engine`` directly, such as when using tools like `Flask SQLAlchemy <http://flask-sqlalchemy.pocoo.org/2.3/>`_. For situations like these, or for situations where you want the ``Client`` to have a `default_query_job_config <https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/generated/google.cloud.bigquery.client.Client.html#google.cloud.bigquery.client.Client>`_, you can pass many arguments in the query of the connection string.
 
@@ -132,7 +208,7 @@ Here are examples of all the supported arguments. Any not present are either for
 
 
 Creating tables
-_______________
+^^^^^^^^^^^^^^^
 
 To add metadata to a table:
 
@@ -145,28 +221,3 @@ To add metadata to a column:
 .. code-block:: python
 
     Column('mycolumn', doc='my column description')
-
-
-Requirements
-============
-
-Install using
-
-- ``pip install pybigquery``
-
-
-Testing
-============
-
-Load sample tables::
-
-    ./scripts/load_test_data.sh
-
-This will create a dataset ``test_pybigquery`` with tables named ``sample_one_row`` and ``sample``.
-
-Set up an environment and run tests::
-
-    pyvenv .env
-    source .env/bin/activate
-    pip install -r dev_requirements.txt
-    pytest

docs/README.rst

@@ -0,0 +1 @@
+../README.rst

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/index.rst

@@ -0,0 +1,20 @@
+.. include:: README.rst
+
+.. include:: multiprocessing.rst
+
+API Reference
+-------------
+.. toctree::
+    :maxdepth: 2
+
+    pybigquery/api
+
+Changelog
+---------
+
+For a list of all ``pybigquery`` releases:
+
+.. toctree::
+   :maxdepth: 2
+
+   changelog

docs/pybigquery/api.rst

@@ -0,0 +1,7 @@
+PyBigQuery API
+==============
+
+.. automodule:: pybigquery.api
+    :members:
+    :undoc-members:
+    :inherited-members: