Add LVK survey page and data listings

CHANGELOG.md

@@ -10,7 +10,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## \[Unreleased\]
 
-(none)
+### Added
+
+- Add 'Surveys' documentation section with pages for ZTF and LVK.
+- Add LVK to Data Listings page.
+
+### Changed
+
+- Reorganize and update data listings.
 
 ## \[v0.3.10\] - 2024-07-22
 

docs/source/conf.py

@@ -45,15 +45,15 @@
     "sphinx_copybutton",
     # [FIXME] do we really need these?
     # "sphinx_autodoc_typehints",  # causes error can't resolve forward reference
-    "sphinx.ext.autosectionlabel",
+    # "sphinx.ext.autosectionlabel",  # does not allow duplicate headings on listings.rst
     "sphinx.ext.mathjax",
 ]
 
 set_type_checking_flag = True  # set typing.TYPE_CHECKING = True
 typehints_defaults = "braces"  # adds (default: ...) after the type
 
 # Make sure the target is unique
-autosectionlabel_prefix_document = True
+# autosectionlabel_prefix_document = True
 # now can reference pages with :ref:`{path/to/page}:{title-of-section}`
 # but can't use this with custom labels, so
 # autosectionlabel_prefix_document = False

docs/source/index.rst

@@ -18,9 +18,9 @@ If you run into trouble, please
     :maxdepth: 1
 
     listings
+    surveys/index
     one-time-setup/index
     faq/index
-    surveys/index
     for-developers/index
 
 .. toctree::

docs/source/listings.rst

@@ -125,3 +125,49 @@ Cloud Storage Buckets
         including image cutouts and metadata. Each alert is stored as a separate Avro file.
         The filename syntax is: `<ztf_topic>/<objectId>/<candid>.avro`.
         Equivalent buckets exist for previous schema versions: v3_3,  v3_1,  v3_0,  v1_8.
+
+.. _data lvk:
+
+LIGO-Virgo-KAGRA (LVK)
+-------------------------------
+
+:ref:`LVK <survey lvk>` is a gravitational wave collaboration producing an alert stream at a rate of 50 - 100 per day.
+
+Pub/Sub Alert Streams
+^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+    :class: tight-table
+    :widths: 25 75
+    :header-rows: 1
+
+    * - Topic
+      - Description
+
+    * - .. centered:: *Data Streams*
+      -
+
+    * - lvk-alerts
+      - LVK alert stream in Pub/Sub.
+        Messages contain the original alert bytes and metadata.
+
+    * - lvk-BigQuery
+      - One message per alert indicating that the alert data is available in a BigQuery table.
+        Table names and alert metadata are in the message attributes. Messages contain no data.
+
+BigQuery Tables
+^^^^^^^^^^^^^^^
+
+.. list-table::
+    :class: tight-table
+    :widths: 15 15 70
+    :header-rows: 1
+
+    * - Dataset
+      - Table
+      - Description
+
+    * - lvk
+      - alerts_O4
+      - Alert data from the LVK O4 observing run. This table is an archive of the lvk-alerts Pub/Sub stream.
+        It has the same schema as the original alert bytes, including nested and repeated fields.

docs/source/surveys/index.rst

@@ -9,3 +9,4 @@ Note that data products may be served in multiple formats -- a complete listing
     :maxdepth: 1
 
     ztf
+    lvk

docs/source/surveys/lvk.rst

@@ -0,0 +1,17 @@
+.. _survey lvk:
+
+LIGO-Virgo-KAGRA (LVK)
+======================
+
+LIGO-Virgo-KAGRA is a collaboration between three gravitational wave observatories.
+It produces an alert stream of gravitational wave candidates at a rate of 50 - 100 per day.
+
+Collaboration resources:
+
+- `LIGO Homepage <https://www.ligo.org/>`__
+- `Virgo Homepage <https://www.virgo-gw.eu/>`__
+- `KAGRA Homepage <https://gwcenter.icrr.u-tokyo.ac.jp/>`__
+
+Data products:
+
+- Alert Stream. Complete documentation can be found at `<https://emfollow.docs.ligo.org/userguide/>`__.