Skip to content

Commit 47926cd

Browse files
tswasttswast
authored
BigQuery: use autosummary to split up API reference docs (googleapis#5340)
* BigQuery: use autosummary to split up API reference docs * Move generated docs stubs to generated directory. * Rename Job enums heading. Comment changes from upstream autosummary. * Remove duplicate documentation of RowIterator.pages.
1 parent 38bd4ab commit 47926cd

File tree

11 files changed

+459
-29
lines changed

11 files changed

+459
-29
lines changed

‎bigquery/google/cloud/bigquery/table.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1084,8 +1084,6 @@ class RowIterator(HTTPIterator):
10841084
page_size (int, optional): The number of items to return per page.
10851085
extra_params (Dict[str, object]):
10861086
Extra query string parameters for the API call.
1087-
1088-
.. autoattribute:: pages
10891087
"""
10901088

10911089
def __init__(self, client, api_request, path, schema, page_token=None,

‎docs/_templates/autosummary/class.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../third_party/sphinx/sphinx/ext/autosummary/templates/autosummary/class.rst

‎docs/_templates/autosummary/module.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../third_party/sphinx/sphinx/ext/autosummary/templates/autosummary/module.rst

‎docs/bigquery/.gitignore‎

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

‎docs/bigquery/reference.rst‎

Lines changed: 92 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,134 @@
11
API Reference
22
~~~~~~~~~~~~~
33

4-
.. automodule:: google.cloud.bigquery
5-
:no-members:
4+
.. currentmodule:: google.cloud.bigquery
5+
6+
The main concepts with this API are:
7+
8+
- :class:`~google.cloud.bigquery.client.Client` manages connections to the
9+
BigQuery API. Use the client methods to run jobs (such as a
10+
:class:`~google.cloud.bigquery.job.QueryJob` via
11+
:meth:`~google.cloud.bigquery.client.Client.query`) and manage resources.
12+
13+
- :class:`~google.cloud.bigquery.dataset.Dataset` represents a
14+
collection of tables.
15+
16+
- :class:`~google.cloud.bigquery.table.Table` represents a single "relation".
617

718
Client
819
======
920

10-
.. automodule:: google.cloud.bigquery.client
11-
:members:
12-
:show-inheritance:
21+
.. autosummary::
22+
:toctree: generated
1323

24+
client.Client
1425

1526
Job
1627
===
1728

18-
.. automodule:: google.cloud.bigquery.job
19-
:members:
20-
:show-inheritance:
29+
Job Configuration
30+
-----------------
31+
32+
.. autosummary::
33+
:toctree: generated
34+
35+
job.QueryJobConfig
36+
job.CopyJobConfig
37+
job.LoadJobConfig
38+
job.ExtractJobConfig
39+
40+
Job Classes
41+
-----------
42+
43+
.. autosummary::
44+
:toctree: generated
45+
46+
job.QueryJob
47+
job.CopyJob
48+
job.LoadJob
49+
job.ExtractJob
50+
job.UnknownJob
51+
52+
Job-Related Types
53+
-----------------
54+
55+
.. autosummary::
56+
:toctree: generated
57+
58+
job.Compression
59+
job.CreateDisposition
60+
job.DestinationFormat
61+
job.Encoding
62+
job.QueryPriority
63+
job.SourceFormat
64+
job.WriteDisposition
2165

2266

2367
Dataset
2468
=======
2569

26-
.. automodule:: google.cloud.bigquery.dataset
27-
:members:
28-
:show-inheritance:
70+
.. autosummary::
71+
:toctree: generated
72+
73+
dataset.Dataset
74+
dataset.DatasetReference
75+
dataset.AccessEntry
2976

3077

3178
Table
3279
=====
3380

34-
.. automodule:: google.cloud.bigquery.table
35-
:members:
36-
:show-inheritance:
81+
.. autosummary::
82+
:toctree: generated
83+
84+
table.Table
85+
table.TableReference
86+
table.Row
87+
table.RowIterator
88+
table.EncryptionConfiguration
89+
table.TimePartitioning
90+
table.TimePartitioningType
3791

3892

3993
Schema
4094
======
4195

42-
.. automodule:: google.cloud.bigquery.schema
43-
:members:
44-
:show-inheritance:
96+
.. autosummary::
97+
:toctree: generated
98+
99+
schema.SchemaField
45100

46101

47102
Query
48103
=====
49104

50-
.. automodule:: google.cloud.bigquery.query
51-
:members:
52-
:show-inheritance:
105+
.. autosummary::
106+
:toctree: generated
107+
108+
query.ArrayQueryParameter
109+
query.ScalarQueryParameter
110+
query.StructQueryParameter
111+
query.UDFResource
53112

54113

55114
External Configuration
56115
======================
57116

58-
.. automodule:: google.cloud.bigquery.external_config
59-
:members:
60-
:show-inheritance:
117+
.. autosummary::
118+
:toctree: generated
119+
120+
external_config.ExternalConfig
121+
external_config.BigtableOptions
122+
external_config.BigtableColumnFamily
123+
external_config.BigtableColumn
124+
external_config.CSVOptions
125+
external_config.GoogleSheetsOptions
61126

62127

63128
Magics
64129
======================
65130

66-
.. automodule:: google.cloud.bigquery.magics
67-
:members:
68-
:show-inheritance:
131+
.. autosummary::
132+
:toctree: generated
133+
134+
magics

‎docs/conf.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
]
5151

5252
# Add any paths that contain templates here, relative to this directory.
53-
templates_path = []
53+
templates_path = ['_templates']
5454

5555
# Allow markdown includes (so releases.md can include CHANGLEOG.md)
5656
# http://www.sphinx-doc.org/en/master/markdown.html
@@ -306,6 +306,10 @@
306306
# and parameter definitions from the __init__ docstring.
307307
autoclass_content = 'both'
308308

309+
# Automatically generate API reference stubs from autosummary.
310+
# http://www.sphinx-doc.org/en/master/ext/autosummary.html#generating-stub-pages-automatically
311+
autosummary_generate = True
312+
309313
# Configuration for intersphinx:
310314
intersphinx_mapping = {
311315
'google-auth': ('https://google-auth.readthedocs.io/en/stable', None),

‎test_utils/scripts/update_docs.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
2424
# Function to build the docs.
2525
function build_docs {
2626
rm -rf docs/_build/
27+
rm -rf docs/bigquery/generated
2728
sphinx-build -W -b html -d docs/_build/doctrees docs/ docs/_build/html/
2829
return $?
2930
}

0 commit comments

Comments
 (0)