diff --git a/docs/source/api-reference/index.rst b/docs/source/api-reference/index.rst index 9b786d7..0303ffa 100644 --- 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 index ba2e407..526b2f7 100644 --- 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 index 2abf417..5839776 100644 --- 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 index 8970d63..b9fe65b 100644 --- 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 index f52ae72..96dbc81 100644 --- 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 index 666f97f..1ae9031 100644 --- 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 index c7af5d7..86c51c9 100644 --- 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 `__ -). +The Google Cloud command-line tools include +`default components `__: +``gcloud``, ``bq``, and ``gsutil``. -To install on Windows, use the -`installer `__. -For Linux and Mac, use: +For complete install instructions, see `Install the gcloud CLI `__ +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 ` 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 index b949ddd..609b582 100644 --- 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 `__ - and login with a Google or Gmail account (go + and login with a Gmail or other Google account (go `here `__ if you need to create one). - Click "Create Project" (A, in the screenshot below). diff --git a/pittgoogle/schema.py b/pittgoogle/schema.py index 6ef701c..9402c97 100644 --- 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: