Add a little documentation

README.md

@@ -1,6 +1,11 @@
-# butler-example-service
+# Example of a service using Butler client/server
 
-Example of accessing Butler data using a web service
-Learn more at https://butler-example-service.lsst.io
+This is an example of accessing Butler data using a web service.  This was
+presented during the "Butler client-server" talk at the [SQRE services
+bootcamp](https://confluence.lsstcorp.org/display/DM/SQuaRE+Bootcamp+-+May+6-10+2024).
 
-butler-example-service is developed with [FastAPI](https://fastapi.tiangolo.com) and [Safir](https://safir.lsst.io).
+Most of the meat is in the `get_coadd_url()` FastAPI handler in
+`src/butlerexampleservice/handlers/external.py` -- the rest of this is just a
+[Safir](https://safir.lsst.io) template project.
+
+An example for a Phalanx deployment of this service can be found [here](https://github.com/lsst-sqre/phalanx/pull/3303).

src/butlerexampleservice/handlers/external.py

@@ -18,18 +18,28 @@
 """FastAPI router for all external handlers."""
 
 
+# The Butler factory loads configuration from the DAF_BUTLER_REPOSITORIES
+# environment variable by default.
+#
+# There should be a single global instance of this factory -- it caches
+# data to allow Butler instances to be created quickly.
 _BUTLER_FACTORY = LabeledButlerFactory()
-_BUTLER_REPOSITORY = "dp02"
 
 
+# This HTTP GET handler returns the URL for a coadded image, given a position
+# in the sky in Rubin's tract/patch skymap.
 @external_router.get("/coadd_url")
 def get_coadd_url(
     tract: int,
     patch: int,
+    # This retrieves a Gafaelfawr access token from headers provided by
+    # GafaelfawrIngress.
     delegated_token: Annotated[str, Depends(auth_delegated_token_dependency)],
 ) -> str:
+    # "dp02" is Data Preview 0.2, currently the only Butler repository
+    # available in the Rubin Science Platform.
     butler = _BUTLER_FACTORY.create_butler(
-        label=_BUTLER_REPOSITORY, access_token=delegated_token
+        label="dp02", access_token=delegated_token
     )
 
     ref = butler.find_dataset(