Minor documentation updates (#52)

doc updates. prep release v0.3.9

CHANGELOG.md

@@ -12,6 +12,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 (none)
 
+## \[v0.3.9\] - 2024-07-02
+
+### Changed
+
+- Minor documentation updates.
+
 ## \[v0.3.8\] - 2024-07-02
 
 ### Changed

docs/source/for-developers/add-new-schema.rst

@@ -1,6 +1,9 @@
 Add a new schema to the registry
 ================================
 
+[FIXME] This information is old. It needs to be updated to describe to the SchemaHelpers and Schema
+child classes.
+
 This page contains instructions for adding a new schema to the registry so that it can be loaded
 using :meth:`pittgoogle.Schemas.get` and used to serialize and deserialize the alert bytes.
 
@@ -24,12 +27,14 @@ Add a new section to the manifest following the template provided there. The fie
 those of a :class:`pittgoogle.schema.Schema`. The ``helper`` field must point to code that can find and load
 the new schema definition; more information below.
 
+[FIXME]
+
 Case 1: The schema definition is not needed in order to deserialize the alert bytes. This is true for
-all Json, and the Avro streams which attach the schema in the data header. Set
-``schemaless_alert_bytes='false'``. Leave ``helper`` and ``path`` as defaults.
+all Json, and the Avro streams which attach the schema in the data header. You should be able to use the
+default helper (see below).
 
 The rest of the cases assume the schema definition is required. This is true for "schemaless" Avro streams
-which do not attach the schema to the data packet. Set ``schemaless_alert_bytes='true'``
+which do not attach the schema to the data packet.
 
 Case 2: You can write some code that will get the schema definition from an external repository. You will
 probably need to write your own ``helper`` method (more below). Follow ``lsst`` as an example. This is

docs/source/for-developers/get-alerts-for-testing.rst

@@ -11,7 +11,7 @@ Setup
 Get alerts from a Pub/Sub subscription
 --------------------------------------
 
-If you need to create the subscription, follow the example in :class:`pittgoogle.Subscription`.
+If you need to create the subscription, follow the example in :class:`pittgoogle.pubsub.Subscription`.
 
 Here are examples that get an alert from each of our "loop" streams:
 

docs/source/for-developers/manage-dependencies-poetry.md

@@ -1,6 +1,6 @@
 # Manage dependencies with Poetry
 
-This page contains instructions for managing the `pittgoogle` package dependencies using [Poetry](https://python-poetry.org/).
+This page contains instructions for managing the `pittgoogle-client` package dependencies using [Poetry](https://python-poetry.org/).
 Poetry was implemented in this repo in [pull #7](https://github.com/mwvgroup/pittgoogle-client/pull/7).
 
 ## Setup your environment
@@ -17,6 +17,19 @@ conda activate poetry-py311
 pip install poetry
 ```
 
+If you come back to this later you may need to reactivate your environment.
+
+```bash
+conda activate poetry-py311
+```
+
+If you want to start over with a fresh environment, deactivate the environment and remove it.
+
+```bash
+conda deactivate
+conda remove --name poetry-py311 --all
+```
+
 ## Install existing dependencies
 
 This repo already contains a poetry.lock file, so running `poetry install` will give you
@@ -28,6 +41,12 @@ If you would rather start over completely, skip ahead to the next section.
 poetry install
 ```
 
+If you want to install the docs dependencies as well, use:
+
+```bash
+poetry install --extras=docs
+```
+
 ## Update Dependency Versions
 
 To upgrade to the latest versions compatible with the pyproject.toml file, you have two options below

pittgoogle/auth.py

@@ -67,6 +67,8 @@ class Auth:
             myauth.credentials
 
         It will first look for a service account key file, then fallback to OAuth2.
+
+    ----
     """
 
     # Strings _below_ the field will make these also show up as individual properties in rendered docs.

pittgoogle/pubsub.py

@@ -295,6 +295,8 @@ class Subscription:
         .. code-block:: python
 
             alerts = subscription.pull_batch(subscription, max_messages=4)  # list of pittgoogle.Alert objects
+
+    ----
     """
 
     name: str = attrs.field()
@@ -485,6 +487,8 @@ def my_batch_callback(results):
             # open the stream in the background and process messages through the callbacks
             # this blocks indefinitely. use `Ctrl-C` to close the stream and unblock
             consumer.stream()
+
+    ----
     """
 
     _subscription: Union[str, Subscription] = attrs.field(
@@ -658,6 +662,8 @@ class Response:
             Anything the user wishes to return. If not `None`, the Consumer will collect the results
             in a list and pass the list to the user's batch callback for further processing.
             If there is no batch callback the results will be lost.
+
+    ----
     """
 
     ack: bool = attrs.field(default=True, converter=bool)

pittgoogle/registry.py

@@ -40,13 +40,13 @@ class Schemas:
         .. code-block:: python
 
             # View list of registered schema names.
-            pittgoogle.Schemas.names
-
-            # View more information about the schemas.
-            pittgoogle.Schemas.manifest
+            pittgoogle.Schemas().names
 
             # Load a schema (choose a name from above and substitute it below).
-            schema = pittgoogle.Schemas.get(schema_name="ztf")
+            schema = pittgoogle.Schemas().get(schema_name="ztf")
+
+            # View more information about all the schemas.
+            pittgoogle.Schemas().manifest
 
     **For Developers**: :doc:`/for-developers/add-new-schema`
 
@@ -90,7 +90,7 @@ def get(schema_name: str | None) -> schema.Schema:
 
         # That's all we know how to check so far.
         raise exceptions.SchemaError(
-            f"{schema_name} not found. For valid names, see `pittgoogle.Schemas.names`."
+            f"{schema_name} not found. For valid names, see `pittgoogle.Schemas().names`."
         )
 
     @property