docs: fixup docs build

pdoc -> sphinx, and fix various build issues.
talkiq · Sep 14, 2023 · 931463c · 931463c
1 parent 304a061
commit 931463c
Show file tree

Hide file tree

Showing 52 changed files with 747 additions and 789 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -98,37 +98,22 @@ jobs:
   docs:
     executor: python311
     steps:
-      - run: pip install pdoc
+      - run: pip install sphinx sphinx-autoapi sphinx-sizzle-theme
       - checkout
-      - attach_workspace:
-          at: rest
-      - run:
-          name: install all sub-projects (aio)
-          command: |
-            pip install -e ./auth
-            pip install -e ./bigquery
-            pip install -e ./datastore
-            pip install -e ./kms
-            pip install -e ./pubsub
-            pip install -e ./storage
-            pip install -e ./taskqueue
-      - run:
-          name: install all sub-projects (rest)
-          command: |
-            cd rest/
-            pip install -e ./auth
-            pip install -e ./bigquery
-            pip install -e ./datastore
-            pip install -e ./kms
-            pip install -e ./pubsub
-            pip install -e ./storage
-            pip install -e ./taskqueue
-      - run: mkdir -p ./build
-      - run: pdoc -o ./build/docs gcloud
+      # TODO: generate gcloud-rest-* docs
+      # - attach_workspace:
+      #     at: rest
+      # TODO: add -W after fixing build issues
+      - run: sphinx-build -b html --keep-going . build/docs/
+      # https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/
+      # Uploading /root/project/build/docs/.nojekyll: SKIPPED, file is empty
+      - run: echo " " > build/docs/.nojekyll
       - persist_to_workspace:
           root: ./build
           paths:
           - ./docs
+      - store_artifacts:
+          path: ./build/docs/
 
   pages:
     docker:
@@ -137,16 +122,16 @@ jobs:
       - checkout
       - attach_workspace:
           at: build
-      - run: npm install -g --silent gh-pages@2.0.1
-      - run:
-          name: configure git creds
-          command: |
-            git config user.email "voiceai-eng+ci@dialpad.com"
-            git config user.name "Vi Eng (CI)"
+      - run: npm install -g --silent gh-pages@6.0.0
       - add_ssh_keys:
           fingerprints:
             - "f6:b5:5d:10:ed:5d:cd:e0:83:28:dd:39:8c:f8:0b:c3"
-      - run: gh-pages --message "[skip ci] updated docs" --dist build/docs
+      # https://github.com/tschaub/gh-pages/issues/354
+      - run: mkdir ./tmp-gh-pages
+      - run:
+          command: gh-pages -u "Vi Eng CI <voiceai-eng+ci@dialpad.com>" -m "[skip ci] updated docs" -td build/docs/
+          environment:
+            CACHE_DIR: ./tmp-gh-pages
 
   github:
     docker:
@@ -268,8 +253,6 @@ workflows:
               only: /master/
             tags:
               ignore: /.*/
-          requires:
-            - build-rest
       - pages:
           filters:
             branches:

diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,7 @@
 **/__pycache__/*
 **/build/*
 **/dist/*
+**/docs/*
 **/venv/*
 *.pyc
 */.coverage

diff --git a/README.rst b/README.rst
@@ -1,5 +1,5 @@
-(Asyncio OR Threadsafe) Google Cloud Client Library for Python
-==============================================================
+(Asyncio OR Threadsafe) Google Cloud Client Libraries for Python
+================================================================
 
 This repository contains a shared codebase for two projects: ``gcloud-aio-*``
 and ``gcloud-rest-*``. Both of them are HTTP implementations of the Google

diff --git a/auth/README.rst b/auth/README.rst
@@ -12,7 +12,7 @@ against Google Cloud. The other ``gcloud-aio-*`` package components accept a
 these components or define one for each. Each component corresponds to a given
 Google Cloud service and each service requires various "`scopes`_".
 
-|pypi| |pythons-aio| |pythons-rest|
+|pypi| |pythons|
 
 Installation
 ------------
@@ -26,32 +26,6 @@ Usage
 
 See `our docs`_.
 
-CLI
-~~~
-
-This project can also be used to help you manually authenticate to test GCP
-routes, eg. we can list our project's uptime checks with a tool such as
-``curl``:
-
-.. code-block:: console
-
-    # using default application credentials
-    curl \
-      -H "Authorization: Bearer $(python3 -c 'from gcloud.rest.auth import Token; print(Token().get())')" \
-      "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/uptimeCheckConfigs"
-
-    # using a service account (make sure to provide a scope!)
-    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service.json
-    curl \
-      -H "Authorization: Bearer $(python3 -c 'from gcloud.rest.auth import Token; print(Token(scopes=["'"https://www.googleapis.com/auth/cloud-platform"'"]).get())')" \
-      "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/uptimeCheckConfigs"
-
-    # using legacy account credentials
-    export GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/legacy_credentials/EMAIL@DOMAIN.TLD/adc.json
-    curl \
-      -H "Authorization: Bearer $(python3 -c 'from gcloud.rest.auth import Token; print(Token().get())')" \
-      "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/uptimeCheckConfigs"
-
 Contributing
 ------------
 
@@ -65,10 +39,6 @@ Please see our `contributing guide`_.
     :alt: Latest PyPI Version (gcloud-aio-auth)
     :target: https://pypi.org/project/gcloud-aio-auth/
 
-.. |pythons-aio| image:: https://img.shields.io/pypi/pyversions/gcloud-aio-auth.svg?style=flat-square&label=python (aio)
-    :alt: Python Version Support (gcloud-aio-auth)
+.. |pythons| image:: https://img.shields.io/pypi/pyversions/gcloud-aio-auth.svg?style=flat-square&label=python
+    :alt: Python Version Support
     :target: https://pypi.org/project/gcloud-aio-auth/
-
-.. |pythons-rest| image:: https://img.shields.io/pypi/pyversions/gcloud-rest-auth.svg?style=flat-square&label=python (rest)
-    :alt: Python Version Support (gcloud-rest-auth)
-    :target: https://pypi.org/project/gcloud-rest-auth/
diff --git a/auth/gcloud/aio/auth/__init__.py b/auth/gcloud/aio/auth/__init__.py
@@ -1,45 +1,75 @@
+# pylint: disable=line-too-long
 """
 This library implements various methods for working with the Google IAM / auth
 APIs. This includes authenticating for the purpose of using other Google APIs,
 managing service accounts and public keys, URL-signing blobs, etc.
 
-## Installation
+Installation
+------------
 
-```console
-$ pip install --upgrade gcloud-aio-auth
-```
+.. code-block:: console
 
-## Usage
+    $ pip install --upgrade gcloud-aio-auth
 
-```python
-from gcloud.aio.auth import IamClient
-from gcloud.aio.auth import Token
+Usage
+-----
 
+.. code-block:: python
 
-client = IamClient()
-pubkeys = await client.list_public_keys()
+    from gcloud.aio.auth import IamClient
+    from gcloud.aio.auth import Token
 
-token = Token()
-print(await token.get())
-```
 
-Additionally, the `Token` constructor accepts the following optional arguments:
+    client = IamClient()
+    pubkeys = await client.list_public_keys()
 
-* `service_file`: path to a [service account][service-account] authorized user
-  file, or any other application credentials. Alternatively, you can pass a
-  file-like object, like an `io.StringIO` instance, in case your credentials
-  are not stored in a file but in memory. If omitted, will attempt to find one
-  on your path or fallback to generating a token from GCE metadata.
-* `session`: an `aiohttp.ClientSession` instance to be used for all requests.
-  If omitted, a default session will be created. If you use the default
-  session, you may be interested in using `Token()` as a context manager
-  (`async with Token(..) as token:`) or explicitly calling the `Token.close()`
-  method to ensure the session is cleaned up appropriately.
-* `scopes`: an optional list of GCP `scopes`_ for which to generate our token.
-  Only valid (and required!) for [service account][service-account]
-  authentication.
+    token = Token()
+    print(await token.get())
 
-[service-account]: https://console.cloud.google.com/iam-admin/serviceaccounts
+Additionally, the ``Token`` constructor accepts the following optional
+arguments:
+
+* ``service_file``: path to a `service account`_ authorized user file, or any
+  other application credentials. Alternatively, you can pass a file-like
+  object, like an ``io.StringIO`` instance, in case your credentials are not
+  stored in a file but in memory. If omitted, will attempt to find one on your
+  path or fallback to generating a token from GCE metadata.
+* ``session``: an ``aiohttp.ClientSession`` instance to be used for all
+  requests. If omitted, a default session will be created. If you use the
+  default session, you may be interested in using ``Token()`` as a context
+  manager (``async with Token(..) as token:``) or explicitly calling the
+  ``Token.close()`` method to ensure the session is cleaned up appropriately.
+* ``scopes``: an optional list of GCP `scopes`_ for which to generate our
+  token. Only valid (and required!) for `service account`_ authentication.
+
+CLI
+---
+
+This project can also be used to help you manually authenticate to test GCP
+routes, eg. we can list our project's uptime checks with a tool such as
+``curl``:
+
+.. code-block:: console
+
+    # using default application credentials
+    curl \
+      -H "Authorization: Bearer $(python3 -c 'from gcloud.rest.auth import Token; print(Token().get())')" \
+      "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/uptimeCheckConfigs"
+
+    # using a service account (make sure to provide a scope!)
+    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service.json
+    curl \
+      -H "Authorization: Bearer $(python3 -c 'from gcloud.rest.auth import Token; print(Token(scopes=["'"https://www.googleapis.com/auth/cloud-platform"'"]).get())')" \
+      "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/uptimeCheckConfigs"
+
+    # using legacy account credentials
+    export GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/legacy_credentials/EMAIL@DOMAIN.TLD/adc.json
+    curl \
+      -H "Authorization: Bearer $(python3 -c 'from gcloud.rest.auth import Token; print(Token().get())')" \
+      "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/uptimeCheckConfigs"
+
+.. _service account: https://console.cloud.google.com/iam-admin/serviceaccounts
+.. _scopes: https://developers.google.com/identity/protocols/oauth2/scopes
 """
 import importlib.metadata
 

diff --git a/auth/poetry.lock b/auth/poetry.lock
diff --git a/auth/poetry.rest.lock b/auth/poetry.rest.lock
@@ -430,4 +430,4 @@ zstd = ["zstandard (>=0.18.0)"]
 [metadata]
 lock-version = "2.0"
 python-versions = ">= 3.8, < 4.0"
-content-hash = "3908fc8aa6dc4fb7a815f828ec6cdbc3cf91eac8d03fdbce4eb54be36142a79f"
+content-hash = "5ad630524b29b6e5c67bf12f8e1b64476c9a1d41dd2a46f1849df62fc90bfc1b"
diff --git a/auth/pyproject.rest.toml b/auth/pyproject.rest.toml
@@ -29,11 +29,15 @@ cryptography = ">= 2.0.0, < 44.0.0"  # pin max to < (major + 3)
 pyjwt = ">= 1.5.3, < 3.0.0"
 requests = ">= 2.2.1, < 3.0.0"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 pytest = ">= 4.0.0, < 8.0.0"
 # pytest-asyncio = ">= 0.16.0, < 0.22.0"
 pytest-mock = ">= 2.0.0, < 4.0.0"
 
+[[tool.poetry.source]]
+name = "pypi"
+priority = "primary"
+
 [tool.pytest.ini_options]
 # addopts = "-Werror"  # TODO: fixme
 # asyncio_mode = "auto"

diff --git a/auth/pyproject.toml b/auth/pyproject.toml
@@ -29,11 +29,15 @@ cryptography = ">= 2.0.0, < 44.0.0"  # pin max to < (major + 3)
 pyjwt = ">= 1.5.3, < 3.0.0"
 # requests = ">= 2.2.1, < 3.0.0"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 pytest = ">= 4.0.0, < 8.0.0"
 pytest-asyncio = ">= 0.16.0, < 0.22.0"
 pytest-mock = ">= 2.0.0, < 4.0.0"
 
+[[tool.poetry.source]]
+name = "pypi"
+priority = "primary"
+
 [tool.pytest.ini_options]
 # addopts = "-Werror"  # TODO: fixme
 asyncio_mode = "auto"

diff --git a/bigquery/README.rst b/bigquery/README.rst
@@ -4,7 +4,7 @@
     This is a shared codebase for ``gcloud-aio-bigquery`` and
     ``gcloud-rest-bigquery``
 
-|pypi| |pythons-aio| |pythons-rest|
+|pypi| |pythons|
 
 Installation
 ------------
@@ -30,10 +30,6 @@ Please see our `contributing guide`_.
     :alt: Latest PyPI Version (gcloud-aio-bigquery)
     :target: https://pypi.org/project/gcloud-aio-bigquery/
 
-.. |pythons-aio| image:: https://img.shields.io/pypi/pyversions/gcloud-aio-bigquery.svg?style=flat-square&label=python (aio)
-    :alt: Python Version Support (gcloud-aio-bigquery)
+.. |pythons| image:: https://img.shields.io/pypi/pyversions/gcloud-aio-bigquery.svg?style=flat-square&label=python
+    :alt: Python Version Support
     :target: https://pypi.org/project/gcloud-aio-bigquery/
-
-.. |pythons-rest| image:: https://img.shields.io/pypi/pyversions/gcloud-rest-bigquery.svg?style=flat-square&label=python (rest)
-    :alt: Python Version Support (gcloud-rest-bigquery)
-    :target: https://pypi.org/project/gcloud-rest-bigquery/
diff --git a/bigquery/gcloud/aio/bigquery/__init__.py b/bigquery/gcloud/aio/bigquery/__init__.py
@@ -1,26 +1,29 @@
+# pylint: disable=line-too-long
 """
 This library implements various methods for working with the Google Bigquery
 APIs.
 
-## Installation
+Installation
+------------
 
-```console
-$ pip install --upgrade gcloud-aio-bigquery
-```
+.. code-block:: console
 
-## Usage
+    $ pip install --upgrade gcloud-aio-bigquery
+
+Usage
+-----
 
 We're still working on documentation -- for now, you can use the
-[smoke test][smoke-test] as an example.
+`smoke test`_ as an example.
 
-## Emulators
+Emulators
+---------
 
-For testing purposes, you may want to use `gcloud-aio-bigquery` along with a
-local emulator. Setting the `$BIGQUERY_EMULATOR_HOST` environment variable to
+For testing purposes, you may want to use ``gcloud-aio-bigquery`` along with a
+local emulator. Setting the ``$BIGQUERY_EMULATOR_HOST`` environment variable to
 the address of your emulator should be enough to do the trick.
 
-[smoke-test]:
-https://github.com/talkiq/gcloud-aio/blob/master/bigquery/tests/integration/smoke_test.py
+.. _smoke test: https://github.com/talkiq/gcloud-aio/blob/master/bigquery/tests/integration/smoke_test.py
 """
 import importlib.metadata
 

diff --git a/bigquery/poetry.lock b/bigquery/poetry.lock
diff --git a/bigquery/poetry.rest.lock b/bigquery/poetry.rest.lock
@@ -523,4 +523,4 @@ zstd = ["zstandard (>=0.18.0)"]
 [metadata]
 lock-version = "2.0"
 python-versions = ">= 3.8, < 4.0"
-content-hash = "f4f44427b5768ade8fbd8964f300bcc624e7719e7757375c1ef69573d9b86ae5"
+content-hash = "eba89a98dd69a344559640ff2b66aece533375ecad913154b2220b6c487fc309"
diff --git a/bigquery/pyproject.rest.toml b/bigquery/pyproject.rest.toml
@@ -23,14 +23,18 @@ classifiers = [
 python = ">= 3.8, < 4.0"
 gcloud-rest-auth = ">= 3.1.0, < 6.0.0"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 gcloud-rest-auth = { path = "../auth" }
 gcloud-rest-datastore = { path = "../datastore" }
 gcloud-rest-storage = { path = "../storage" }
 pytest = ">= 4.0.0, < 8.0.0"
 # pytest-asyncio = ">= 0.16.0, < 0.22.0"
 pytest-mock = ">= 2.0.0, < 4.0.0"
 
+[[tool.poetry.source]]
+name = "pypi"
+priority = "primary"
+
 [tool.pytest.ini_options]
 # addopts = "-Werror"  # TODO: fixme
 # asyncio_mode = "auto"