Docs cleanup (#53)

Minor docs cleanup. Adding comments and links for clarity.
mwvgroup · Jul 11, 2024 · 7d8f55e · 7d8f55e
1 parent 331bbea
commit 7d8f55e
Show file tree

Hide file tree

Showing 9 changed files with 33 additions and 25 deletions.
diff --git a/docs/source/api-reference/index.rst b/docs/source/api-reference/index.rst
@@ -1,17 +1,18 @@
+.. _api reference:
+
 pittgoogle
 ==========
 
-.. Listing the subset of class the user will interact with most.
-.. Is this what we want the package index page to look like? # [TODO]
+[FIXME] This lists a subset of classes the user will interact with most.
+Is this what we want?
+Should at least add some text to clarify.
 
 .. autosummary::
 
-    .. autosummary::
-
-        pittgoogle.alert.Alert
-        pittgoogle.bigquery.Table
-        pittgoogle.pubsub.Consumer
-        pittgoogle.pubsub.Subscription
-        pittgoogle.pubsub.Topic
-        pittgoogle.registry.ProjectIds
-        pittgoogle.registry.Schemas
+    pittgoogle.alert.Alert
+    pittgoogle.bigquery.Table
+    pittgoogle.pubsub.Consumer
+    pittgoogle.pubsub.Subscription
+    pittgoogle.pubsub.Topic
+    pittgoogle.registry.ProjectIds
+    pittgoogle.registry.Schemas
diff --git a/docs/source/faq/what-is-bigquery.rst b/docs/source/faq/what-is-bigquery.rst
@@ -1,4 +1,4 @@
 What is BigQuery?
 =================
 
-Google Cloud's BigQuery is ... # [TODO]
+Google Cloud's BigQuery is ... # [TODO] I've written this several times before -- find them.
diff --git a/docs/source/faq/what-is-cloud-run.rst b/docs/source/faq/what-is-cloud-run.rst
@@ -1,4 +1,4 @@
 What is Cloud Run?
 ==================
 
-Google Cloud's Cloud Run is ... # [TODO]
+Google Cloud's Cloud Run is ... # [TODO] I've written this several times before -- find them.
diff --git a/docs/source/faq/what-is-cloud-storage.rst b/docs/source/faq/what-is-cloud-storage.rst
@@ -1,4 +1,4 @@
 What is Cloud Storage?
 ======================
 
-Google Cloud's Cloud Storage is ... # [TODO]
+Google Cloud's Cloud Storage is ... # [TODO] I've written this several times before -- find them.
diff --git a/docs/source/faq/what-is-pubsub.rst b/docs/source/faq/what-is-pubsub.rst
@@ -1,4 +1,4 @@
 What is Pub/Sub?
 =================
 
-Google Cloud's Pub/Sub is ... # [TODO]
+Google Cloud's Pub/Sub is ... # [TODO] I've written this several times before -- find them.
diff --git a/docs/source/for-developers/get-alerts-for-testing.rst b/docs/source/for-developers/get-alerts-for-testing.rst
@@ -1,6 +1,8 @@
 Get alerts for testing
 ======================
 
+[FIXME] Everyone needs this, not just developers. Move this page to the user-demos repo.
+
 Setup
 -----
 

diff --git a/docs/source/one-time-setup/google-sdk.rst b/docs/source/one-time-setup/google-sdk.rst
@@ -10,20 +10,20 @@ Google Cloud SDK
     is helpful for some use cases. If you don't know whether you need this,
     skip it for now.
 
-The Google Cloud command-line tools include: gcloud, bq, and gsutil (see
-`default components <https://cloud.google.com/sdk/docs/components#default_components>`__
-).
+The Google Cloud command-line tools include
+`default components <https://cloud.google.com/sdk/docs/components#default_components>`__:
+``gcloud``, ``bq``, and ``gsutil``.
 
-To install on Windows, use the
-`installer <https://cloud.google.com/sdk/docs/downloads-interactive#windows>`__.
-For Linux and Mac, use:
+For complete install instructions, see `Install the gcloud CLI  <https://cloud.google.com/sdk/docs/install>`__
+Windows users will need to use the installer found at that link.
+For Linux and Mac, the basic command is:
 
 .. code-block:: bash
 
     curl https://sdk.cloud.google.com | bash
 
 In either case, follow the instructions to complete the installation.
-Then open a new terminal or restart your shell.
+Then, open a new terminal or restart your shell.
 Make sure your :ref:`environment variables <set env vars>` are set, reset them if needed.
 Then initialize gcloud using:
 
@@ -32,6 +32,7 @@ Then initialize gcloud using:
     gcloud init
 
 and follow the directions.
+You will likely need to authenticate using the Gmail address (or similar) that is registered with your Google Cloud project.
 Note that this may open a browser and ask you to complete the setup there.
 
 The remaining steps are recommended but optional.

diff --git a/docs/source/one-time-setup/project.rst b/docs/source/one-time-setup/project.rst
@@ -8,7 +8,7 @@ Google Cloud Projects
     :local:
 
 You will need to be authenticated to a Google Cloud project in order to access data served by Pitt-Google Broker.
-Projects are free.
+Projects are free and a credit card is not required.
 They are easy to create and delete.
 One user can have many projects, and users can share projects.
 Access is usually managed through the Google Console using a Gmail account, as shown below.
@@ -24,7 +24,7 @@ Setup a Google Cloud project
 
 -   Go to the
     `Cloud Resource Manager <https://console.cloud.google.com/cloud-resource-manager>`__
-    and login with a Google or Gmail account (go
+    and login with a Gmail or other Google account (go
     `here <https://accounts.google.com/signup>`__ if you need to create one).
 
 -   Click "Create Project" (A, in the screenshot below).

diff --git a/pittgoogle/schema.py b/pittgoogle/schema.py
@@ -253,9 +253,13 @@ def deserialize(self, alert_bytes: bytes) -> dict:
 
 
 class _ConfluentWireAvroSchema(Schema):
-    """Schema to serialize and deserialize alert bytes in the Avro Confluent Wire Format."""
+    """Schema to serialize and deserialize alert bytes in the Avro Confluent Wire Format.
+
+    https://docs.confluent.io/platform/current/schema-registry/fundamentals/serdes-develop/index.html#wire-format
+    """
 
     def serialize(self, alert_dict: dict) -> bytes:
+        # [TODO]
         raise NotImplementedError("Confluent Wire Format not yet supported.")
 
     def deserialize(self, alert_bytes: bytes) -> dict: