Improve documentation

docs/source/index.rst

@@ -34,16 +34,10 @@
     api-reference/utils
 
 pittgoogle-client
-==============================================
+=================
 
-`pittgoogle-client` is a python library that facilitates access to astronomy data that lives in Google Cloud services.
-It is being developed  the `Pitt-Google alert broker <https://github.com/mwvgroup/Pitt-Google-Broker>`__ is curated and maintained  available in Google Cloud.
-
-**Initial setup** for data access requires 2 steps:
-
-#.  :ref:`install`
-
-#.  :ref:`Authenticate to Google Cloud <authentication>`
+`pittgoogle-client` is a python library for accessing astronomy data served by
+`Pitt-Google Alert Broker <https://github.com/mwvgroup/Pitt-Google-Broker>`__.
 
 If you run into trouble, please
 `open an Issue <https://github.com/mwvgroup/pittgoogle-client/issues>`__.

pittgoogle/alert.py

@@ -1,26 +1,5 @@
 # -*- coding: UTF-8 -*-
-"""Classes to facilitate working with astronomical alerts.
-
-.. contents::
-   :local:
-   :depth: 2
-
-Usage Examples
----------------
-
-Load an alert from disk:
-
-.. code-block:: python
-
-    import pittgoogle
-
-    path = "path/to/ztf_alert.avro"  # point this to a file containing an alert
-    alert = pittgoogle.Alert.from_path(path, schema_name="ztf")
-
-API
-----
-
-"""
+"""Classes to facilitate working with astronomical alerts."""
 import base64
 import importlib.resources
 import io
@@ -47,8 +26,9 @@
 class Alert:
     """Pitt-Google container for an astronomical alert.
 
-    Don't call this directly.
-    Use one of the `from_*` methods instead.
+    Instances of this class are returned by other calls like :meth:`pittgoogle.Subscription.pull_batch`,
+    so it is often not necessary to instantiate this directly.
+    In cases where you do want to create an `Alert` directly, use one of the `from_*` methods like `pittgoogle.Alert.from_dict`.
 
     All parameters are keyword only.
 

pittgoogle/pubsub.py

@@ -449,8 +449,11 @@ def delete(self) -> None:
     def pull_batch(self, max_messages: int = 1) -> List["Alert"]:
         """Pull a single batch of messages.
 
-        Recommended for testing. Not recommended for long-running listeners (use the
-        :meth:`~Consumer.stream` method instead).
+        This method is recommended for use cases that need a small number of alerts on-demand,
+        often for testing and development.
+
+        This method is *not* recommended for long-running listeners as it is likely to be unstable
+        -- use :meth:`~Consumer.stream` instead.
 
         Parameters
         ----------

pittgoogle/registry_manifests/schemas.yml

@@ -5,12 +5,27 @@
 #   same name (path stem) as the schema. Avro is the only file type currently implemented, and the file name
 #   must end with ".avsc".
 # - The path must be relative to the package directory or null if no schema file is being registered.
+#
+#
+# # TEMPLATE
+# # See the registry.Schemas docstring for an explanation of the fields.
+# - name: ""
+#   description: ""
+#   helper: ""
+#   path: ""
+#
+# ELASTICC alerts
 - name: "elasticc.v0_9_1.alert"
   description: "Avro schema of alerts published by ELAsTiCC."
   path: "schemas/elasticc/elasticc.v0_9_1.alert.avsc"
+# ELASTICC classifications
 - name: "elasticc.v0_9_1.brokerClassification"
   description: "Avro schema of alerts to be sent to DESC containing classifications of ELAsTiCC alerts."
   path: "schemas/elasticc/elasticc.v0_9_1.brokerClassification.avsc"
+# Rubin alerts
+- name: ""  # [TODO]
+  description:
+# ZTF alerts
 - name: "ztf"
   description: "ZTF schema. The ZTF survey publishes alerts in Avro format with the schema attached in the header. Pitt-Google publishes ZTF alerts in json format. This schema covers both cases."
   path: null

pyproject.toml

@@ -1,3 +1,6 @@
+# https://packaging.python.org/en/latest/guides/writing-pyproject-toml
+# https://python-poetry.org/docs/basic-usage/#specifying-dependencies
+#
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
@@ -23,6 +26,8 @@ classifiers = [
 ]
 
 [tool.poetry.dependencies]
+# https://python-poetry.org/docs/dependency-specification/
+# https://python-poetry.org/docs/dependency-specification/#git-dependencies
 python = "^3.9"
 attrs = ">=23.1"
 astropy = ">=5.3"