Clean up and improve documentation (#356)

Co-authored-by: Evan Goetz <[email protected]>
gwpy · Nov 1, 2023 · 821d1a2 · 821d1a2
1 parent f658c15
commit 821d1a2
Show file tree

Hide file tree

Showing 9 changed files with 68 additions and 51 deletions.
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -1,3 +1,5 @@
+.. _cli-page:
+
 ######################
 Command-line interface
 ######################
@@ -19,28 +21,28 @@ Day mode
 
 To run in daily summary mode, the following command-line options are available:
 
-.. command-output:: python ../bin/gw_summary day --help
+.. command-output:: python gw_summary day --help
 
 Week mode
 ---------
 
 The arguments in weekly mode are as follows:
 
-.. command-output:: python ../bin/gw_summary week --help
+.. command-output:: python gw_summary week --help
 
 Month mode
 ----------
 
 In monthly mode:
 
-.. command-output:: python ../bin/gw_summary month --help
+.. command-output:: python gw_summary month --help
 
 GPS mode
 --------
 
 To run within a specific (but arbitrary) range of GPS seconds:
 
-.. command-output:: python ../bin/gw_summary gps --help
+.. command-output:: python gw_summary gps --help
 
 Batch mode
 ==========
@@ -54,4 +56,4 @@ and run jobs in parallel.
 To see all the available arguments and options for this tool, you can run
 with `--help` as usual:
 
-.. command-output:: python ../bin/gw_summary_pipe --help
+.. command-output:: python gw_summary_pipe --help
diff --git a/docs/examples/first.png b/docs/examples/first.png
diff --git a/docs/examples/imc.png b/docs/examples/imc.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -71,7 +71,6 @@ GWSumm is distributed under the `GNU General Public License`_.
    cli
    automation
    tabs/index
-   tabs/flavour
    tabs/websites
    tabs/modes
    tabs/api

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -9,9 +9,9 @@ The summary pages were developed in collaboration between the LIGO Laboratory
 and the GEO600 project with the goal of generating an automated daily summary
 of laser-interferometer operations and performance.
 
-As of summary 2014, the summary pages are extensively used to characterise
-data from the new `Advanced LIGO <https://www.advancedligo.mit.edu/>`_
-instruments as they are being commissioned for future observing runs.
+The LIGO Summary Pages are used to characterize and monitor the status
+of the detectors and their subsystems. In addition, data products and
+webpages from other analysis tools are included in the Summary Pages.
 
 The output acts as a kind of daily magazine, allowing instrument scientists
 and data analysis teams a archived, searchable summary of the key figures of
@@ -40,22 +40,32 @@ should be manipulated, and how it should all be displayed.
 These configuration files are made up ``[tab-xxx]`` section with the following
 format:
 
-.. literalinclude:: ../share/examples/imc.ini
-   :language: ini
+.. code-block:: ini
 
-This block defines the ``IMC`` tab, with a ``name`` (and a ``shortname``),
-which should contain a single ``timeseries`` plot of the
-``L1:IMC-PWR_IN_OUT_DQ`` channel.
-The plot has been customised with a y-axis limit and a title.
+  [tab-IMC]
+  name = Input mode cleaner
+  shortname = IMC
+  1 = L1:IMC-PWR_IN_OUT_DQ timeseries
+  1-ylim = 0,80
+  1-title = 'Power into IMC'
+  [html]
+  issues =
 
-This tab is then generate by passing it to the `gw_summary` executable, along
+This block defines the ``IMC`` tab, with a ``name`` (and a ``shortname``):
+a single ``timeseries`` plot of the ``L1:IMC-PWR_IN_OUT_DQ`` channel.
+The plot has been customised with a y-axis limit and a title. This
+also defines the required ``[html]`` section, where the required key
+``issues`` is defined. This example can be saved to a file called ``imc.ini``.
+
+This tab is then generated by passing it to the `gw_summary` executable, along
 with some GPS times over which to run:
 
 .. code-block:: bash
 
-   $ gw_summary gps 'June 1 2014 00:00' 'June 1 2014 01:00' --config-file imc.ini
+   $ gw_summary gps 'Feb 29 2020 00:00' 'Feb 29 2020 01:00' --config-file imc.ini
 
-This minimal setup will produce the following HTML page:
+This minimal setup will produce the following HTML page
+`1266969618-1266973218/imc/index.html`:
 
 .. image:: examples/imc.png
    :width: 80%

diff --git a/docs/tabs/flavour.rst b/docs/tabs/flavour.rst
diff --git a/docs/tabs/index.rst b/docs/tabs/index.rst
@@ -6,6 +6,10 @@
 Introduction to Tabs
 ####################
 
+GWsumm can be used either from the command line as described in
+:ref:`CLI interface <cli-page>` or as a package to progromatically
+generate pages called "tabs".
+
 A `Tab` is a single, configurable page of output, containing some data.
 Each `Tab` is written in its own HTML page, and can be written to contain
 any set of data, with any format.
@@ -22,13 +26,20 @@ A simple `Tab` can be created in only two steps
 
 .. code-block:: python
 
+   from gwsumm.tabs import Tab
    mytab = Tab('My first tab')
    mytab.write_html("This tab doesn't do very much")
 
-This will create two directories under the current one,
+This will create a directory under the current one,
 
 - ``my_first_tab/`` containing the HTML for the new tab
-- ``static/`` containing all of the stylesheets and javascript files that make the page functional
+
+The output webpage looks like:
+
+.. image:: examples/first.png
+   :width: 80%
+   :align: center
+   :alt: First GWSumm example screenshot
 
 The content given to `Tab.write_html` is passed along untouched, so can contain any HTML you like.
 

diff --git a/docs/tabs/modes.rst b/docs/tabs/modes.rst
@@ -9,7 +9,7 @@
 In its simplest form, the `Tab` is essentially a blank canvas on which to write whatever you want.
 However, the original mandate for GWSumm was to provide a framework in which to generate automatic summaries of LIGO data, over a given timescale.
 
-To handle data processing, rather than static HTML generation, each `Tab` has a flavour, based on its relation to any interval in time
+To handle data processing, rather than static HTML generation, each `Tab` has a type, based on its relation to any interval in time
 
 .. currentmodule:: gwsumm.tabs.core
 
@@ -21,14 +21,13 @@ To handle data processing, rather than static HTML generation, each `Tab` has a
    IntervalTab
    EventTab
 
-The 'flavour' of a `Tab` is set automatically when it is created based on the value of the :attr:`~Tab.mode` attribute, so you don't need to remember the above objects.
+The type of a `Tab` is set automatically when it is created based on the value of the :attr:`~Tab.mode` attribute, so you don't need to remember the above objects.
 
 =====
 Modes
 =====
 
-All tabs have a :attr:`~Tab.mode`, loosely based around the time interval of interest.
-GWSumm support seven modes:
+GWSumm currently support seven different `Tab` modes:
 
 ==========  ====  =============================================================
 Mode        Enum  Description
@@ -46,9 +45,16 @@ Mode        Enum  Description
 Assigning modes
 ===============
 
-Each `Tab` must be assigned a mode, which can either be done locally, by passing the `~Tab.mode` keyword argument when creating a `Tab`, or globally, by using the :meth:`gwsumm.mode.set_mode`; this sets the default mode for all tabs created in this session.
+Each `Tab` will be assigned a mode (unless specified as follows, the default mode
+is ``STATIC``). The assignment can be done on a per-tab basis by
+passing the `~Tab.mode` keyword argument when creating a `Tab`, or
+globally, by using the :meth:`gwsumm.mode.set_mode`. The latter sets
+the default mode for all subsequent tabs created in this session.
 
-If a :attr:`~Tab.mode` is given that assocaites with a GPS time or times, these must be given via the `~IntervalTab.span` or `~EventTab.gpstime` keyword arguments, otherwise a `TypeError` will be raised.
+If a :attr:`~Tab.mode` is given that associates with a GPS time or
+times, these must be given via the `~IntervalTab.span` or
+`~EventTab.gpstime` keyword arguments, otherwise a `TypeError` will be
+raised. The `span` tuple is the ``(GPS start time, GPS end time)``
 
 .. code-block:: python
 

diff --git a/docs/tabs/websites.rst b/docs/tabs/websites.rst
@@ -14,6 +14,7 @@ The key difference between standalone pages and a website is the ability to navi
 
 .. code-block:: python
 
+   from gwsumm.tabs import Tab
    tab1 = Tab('Tab 1')
    tab2 = Tab('Tab 2')
    tabs = [tab1, tab2]
@@ -43,4 +44,16 @@ Here we have set a `parent` tab for 2A, and used the same for 2B, which creates
 Tab groups
 ----------
 
-For even larger websites, sets of tabs under a single parent can be further separated into `groups <Tab.group>`.
+For even larger websites, sets of tabs under a single parent can be
+further separated into `groups <Tab.group>`. For example, to put 2A
+into group `1` and 2B into group `2`, we can write:
+
+.. code-block:: python
+
+   tab1 = Tab('Tab 1')
+   tab2a = Tab('A', parent='Tab 2', group='1')
+   tab2b = Tab('B', parent=tab2a.parent, group='2')
+   tabs = [tab1, tab2a, tab2b]
+   tab1.write_html('This is tab 1', tabs=tabs)
+   tab2a.write_html('This is tab 2A', tabs=tabs)
+   tab2b.write_html('This is tab 2B', tabs=tabs)