docs: add how-to guide and include API reference

README.rst

@@ -18,21 +18,6 @@ Pandas Data Types for SQL systems (BigQuery, Spanner)
 .. _Library Documentation: https://googleapis.dev/python/db-dtypes/latest
 
 
-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
 ------------
 

docs/conf.py

@@ -351,7 +351,7 @@
     "grpc": ("https://grpc.github.io/grpc/python/", None),
     "proto-plus": ("https://proto-plus-python.readthedocs.io/en/latest/", None),
     "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
-    "pandas": ("http://pandas.pydata.org/pandas-docs/dev", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
 }
 
 

docs/index.rst

@@ -1,5 +1,14 @@
 .. include:: README.rst
 
+How-to Guides
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+
+
 API Reference
 -------------
 

docs/reference.rst

@@ -1,4 +1,4 @@
 API Reference
 ^^^^^^^^^^^^^
 
-.. automodule:: db_dtypes.version
+.. automodule:: db_dtypes

docs/samples

@@ -0,0 +1 @@
+../samples

docs/usage.rst

@@ -0,0 +1,80 @@
+Using the db-dtypes package
+---------------------------
+
+Importing the :mod:`db_dtypes` module registers the extension dtypes for use
+in pandas.
+
+Construct a date :class:`~pandas.Series` with strings in ``YYYY-MM-DD`` format
+or :class:`datetime.date` objects.
+
+.. literalinclude:: samples/snippets/pandas_date_and_time.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_pandas_date_create]
+   :end-before: [END bigquery_pandas_date_create]
+
+Working with dates
+^^^^^^^^^^^^^^^^^^
+
+Convert a date :class:`~pandas.Series` to a ``datetime64`` Series with
+:meth:`~pandas.Series.astype`. The resulting values use midnight as the
+time part.
+
+.. literalinclude:: samples/snippets/pandas_date_and_time.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_pandas_date_as_datetime]
+   :end-before: [END bigquery_pandas_date_as_datetime]
+
+Just like ``datetime64`` values, date values can be subtracted. This is
+equivalent to first converting to ``datetime64`` and then subtracting.
+
+.. literalinclude:: samples/snippets/pandas_date_and_time.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_pandas_date_sub]
+   :end-before: [END bigquery_pandas_date_sub]
+
+Just like ``datetime64`` values, :class:`~pandas.tseries.offsets.DateOffset`
+values can be added to them.
+
+.. literalinclude:: samples/snippets/pandas_date_and_time.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_pandas_date_add_offset]
+   :end-before: [END bigquery_pandas_date_add_offset]
+
+
+Working with times
+^^^^^^^^^^^^^^^^^^
+
+Construct a time :class:`~pandas.Series` with strings in ``HH:MM:SS.fraction``
+24-hour format or :class:`datetime.time` objects.
+
+.. literalinclude:: samples/snippets/pandas_date_and_time.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_pandas_time_create]
+   :end-before: [END bigquery_pandas_time_create]
+
+Convert a time :class:`~pandas.Series` to a ``timedelta64`` Series with
+:meth:`~pandas.Series.astype`.
+
+.. literalinclude:: samples/snippets/pandas_date_and_time.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_pandas_time_as_timedelta]
+   :end-before: [END bigquery_pandas_time_as_timedelta]
+
+
+Combining dates and times
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Combine a date :class:`~pandas.Series` with a time :class:`~pandas.Series` to
+create a ``datetime64`` :class:`~pandas.Series`.
+
+   .. literalinclude:: samples/snippets/pandas_date_and_time.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_pandas_combine_date_time]
+   :end-before: [END bigquery_pandas_combine_date_time]

owlbot.py

@@ -31,7 +31,9 @@
     unit_test_python_versions=["3.6", "3.7", "3.8", "3.9"],
     system_test_python_versions=["3.8"],
     cov_level=100,
-    intersphinx_dependencies={"pandas": "http://pandas.pydata.org/pandas-docs/dev"},
+    intersphinx_dependencies={
+        "pandas": "https://pandas.pydata.org/pandas-docs/stable/"
+    },
 )
 s.move(templated_files, excludes=["docs/multiprocessing.rst"])
 

samples/snippets/pandas_date_and_time.py

@@ -14,60 +14,53 @@
 
 
 def pandas_date_and_time():
-    # fmt: off
-    # [START bigquery_date_create]
+    # [START bigquery_pandas_date_create]
 
     import datetime
     import pandas as pd
     import db_dtypes  # noqa import to register dtypes
 
-    dates = pd.Series(
-        [datetime.date(2021, 9, 17), '2021-9-18'],
-        dtype='date')
+    dates = pd.Series([datetime.date(2021, 9, 17), "2021-9-18"], dtype="date")
 
-    # [END bigquery_date_create]
-    # [START bigquery_date_as_datetime]
+    # [END bigquery_pandas_date_create]
+    # [START bigquery_pandas_date_as_datetime]
 
     datetimes = dates.astype("datetime64")
 
-    # [END bigquery_date_as_datetime]
-    # [START bigquery_date_sub]
+    # [END bigquery_pandas_date_as_datetime]
+    # [START bigquery_pandas_date_sub]
 
-    dates2 = pd.Series(['2021-1-1', '2021-1-2'], dtype='date')
+    dates2 = pd.Series(["2021-1-1", "2021-1-2"], dtype="date")
     diffs = dates - dates2
 
-    # [END bigquery_date_sub]
-    # [START bigquery_date_do]
+    # [END bigquery_pandas_date_sub]
+    # [START bigquery_pandas_date_add_offset]
 
     do = pd.DateOffset(days=1)
     after = dates + do
     before = dates - do
 
-    # [END bigquery_date_do]
-    # [START bigquery_time_create]
+    # [END bigquery_pandas_date_add_offset]
+    # [START bigquery_pandas_time_create]
 
-    times = pd.Series(
-        [datetime.time(1, 2, 3, 456789), '12:00:00.6'],
-        dtype='time')
+    times = pd.Series([datetime.time(1, 2, 3, 456789), "12:00:00.6"], dtype="time")
 
-    # [END bigquery_time_create]
-    # [START bigquery_time_as_timedelta]
+    # [END bigquery_pandas_time_create]
+    # [START bigquery_pandas_time_as_timedelta]
 
     timedeltas = times.astype("timedelta64")
 
-    # [END bigquery_time_as_timedelta]
-    # [START bigquery_combine_date_time]
+    # [END bigquery_pandas_time_as_timedelta]
 
-    combined = datetimes + timedeltas
+    # Combine datetime64 and timedelta64 to confirm adding dates and times are
+    # equivalent.
+    combined0 = datetimes + timedeltas
 
-    # [END bigquery_combine_date_time]
-    combined0 = combined
-    # [START bigquery_combine2_date_time]
+    # [START bigquery_pandas_combine_date_time]
 
     combined = dates + times
 
-    # [END bigquery_combine2_date_time]
-    # fmt: on
+    # [END bigquery_pandas_combine_date_time]
 
     return (
         dates,