add segments section to offline analysis docs

doc/source/cbc_analysis.rst

@@ -256,6 +256,53 @@ consider. In practice, the segments file we produce will only contain the
 segments we want. Users will typically not change any of these options once they
 are set for a given instrument and observing run.
 
+Section: Segments
+""""""""""""""""""
+
+The ``segments`` section specifies how to generate segments and vetoes for the
+workflow. There are two backends to determine where to query segments and vetoes
+from, ``gwosc`` (public) and ``dqsegdb`` (authenticated).
+
+An example of configuration with the ``gwosc`` backend looks like:
+
+.. code-block:: yaml
+
+    segments:
+      backend: gwosc
+      vetoes:
+        category: CAT1
+
+Here, the ``backend`` is set to ``gwosc`` so both segments are vetoes are determined
+by querying the GWOSC server. There is no additional configuration needed to query
+segments, but for vetoes, we also need to specify the ``category`` used for vetoes.
+This can be one of ``CAT1``, ``CAT2``, or ``CAT3``. By default, segments are generated
+by applying ``CAT1`` vetoes as recommended by the Detector Characterization group.
+
+An example of configuration with the ``dqsegdb`` backend looks like:
+
+.. code-block:: yaml
+
+    segments:
+      backend: dqsegdb
+      science:
+        H1: DCS-ANALYSIS_READY_C01:1
+        L1: DCS-ANALYSIS_READY_C01:1
+        V1: ITF_SCIENCE:2
+      vetoes:
+        category: CAT1
+        veto-definer:
+          file: H1L1V1-HOFT_C01_V1ONLINE_O3_CBC.xml
+          version: O3b_CBC_H1L1V1_C01_v1.2
+          epoch: O3
+
+Here, the ``backend`` is set to ``dqsegdb`` so both segments are vetoes are determined
+by querying the DQSEGDB server. To query segments, one needs to specify the flag used
+per instrument to query segments from. For vetoes, we need to specify the ``category``
+used for vetoes as with the ``dqsegdb`` backend. Additionally, a veto definer file is
+used to determine which flags are used for which veto categories. The file need not be
+provided, the ``file``, ``version`` and ``epoch`` fully specify how to access the veto
+definer file used for generating vetoes.
+
 Section: PSD
 """"""""""""""