Maintenance will be performed on git.ligo.org, chat.ligo.org, containers.ligo.org, and docs.ligo.org on the morning of Tuesday 11th August 2020, starting at approximately 9am PDT. It is expected to take around 20 minutes and there will be a short period of downtime (less than five minutes) towards the end of the maintenance window. Please direct any comments, questions, or concerns to computing-help@ligo.org.

Add comprehensive documentation

parent 5aa993b1
......@@ -3,7 +3,6 @@ stages:
- test
# -- build ------------------
.build: &build
stage: build
after_script:
......@@ -72,8 +71,8 @@ build:debian:stretch:
<<: *build_debian
image: debian:stretch
# -- test -------------------
# -- test -------------------
.test: &test
stage: test
image: python
......@@ -99,3 +98,17 @@ test:python3.6:
test:python3.7:
<<: *test
image: python:3.7
# -- pages ------------------
pages:
image: python:3.6-slim
script:
- apt-get update
- apt-get install build-essential git -y
- pip install sphinx sphinx_rtd_theme
- cd docs
- make html
- mv build/html ../public
artifacts:
paths:
- public
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
API
===
This section provides detailed information about the :py:class:`ligo.gracedb.rest.GraceDb` client class which is the primary method for accessing the GraceDB API.
.. autoclass:: ligo.gracedb.rest.GraceDb
:members:
:inherited-members:
:no-undoc-members:
:exclude-members: eels, writeEel
A separate :class:`GraceDbBasic` class had been provided in the past for password-based authentication, but that functionality is now included in the :class:`GraceDb` class.
:py:class:`ligo.gracedb.rest.GraceDbBasic` is still provided for legacy compatibility, but it is now an exact duplicate of the :py:class:`ligo.gracedb.rest.GraceDb` class.
Changelog
=========
2.2.2
-----
:Date: March 8, 2019
- Bugfix for Python 3 compatibility: remove all usage of ``dict.keys()`` and ``dict.values()``
- Bugfix handling of :obj:`bytes` responses in command-line interface
- Improve command-line interface help
2.2.1
-----
:Date: March 1, 2019
- Bugfix default service URL for command-line interface
- Bugfix packaging
2.2.0
-----
:Date: February 22, 2019
- Full rework of command-line tool
- Add option for handling legacy ``tagname`` kwarg (instead of ``tag_name``) to :py:meth:`ligo.gracedb.rest.GraceDb.writeLog`
- Add optional ``MassGap`` parameter to :py:meth:`ligo.gracedb.rest.GraceDb.createVOEvent`
2.1.2
-----
:Date: February 5, 2019
- Remove ``skymap_image_filename`` from :py:meth:`ligo.gracedb.rest.GraceDb.createVOEvent`
- Add optional kwarg ``max_results`` to :py:meth:`ligo.gracedb.rest.GraceDb.events` and :py:meth:`ligo.gracedb.rest.GraceDb.superevents`
- Improve testing configuration by adding pytest and tox
2.1.1
-----
:Date: December 5, 2018
- Add new optional parameters to :py:meth:`ligo.gracedb.rest.GraceDb.createVOEvent`:
- ``BNS``: probability that source is a binary neutron star merger
- ``NSBH``: probability that source is a neutron star - black hole binary merger
- ``BBH``: probability that the source is a binary black hole merger
- ``Terrestrial``: probability that the source is a background noise fluctuation or glitch
- Remove one optional parameter from :py:meth:`ligo.gracedb.rest.GraceDb.createVOEvent`: ``vetted``, specifying whether the candidate has undergone basic human vetting
- Minor bugfixes/changes to integration tests
2.1.0
-----
:Date: November 29, 2018
- Improve error handling for failed attempts to get service information from API
- Consolidate all authentication types under a single client class
- Add unit tests for handling of credentials
2.0.1
-----
:Date: October 3, 2018
- Bugfix for truthiness checks for numeric arguments
- Remove permissions detail retrieval (no longer available on server)
2.0.0
-----
:Date: September 25, 2018
- Add comprehensive compatibility for Python 3.4+
- Add functionality for managing superevent signoffs and permissions
- Remove temporary deprecation measure for including VOEvent file text in response
- Add an option for specifying a server API version
- Update unit tests
2.0.0.dev1
----------
:Date: July 25, 2018
- Add CI configuration
- Update and centralize package version handling
- Remove ``bin/gracedb`` executable, now built by setup.py as an ``entry_point``
- Add client version to request headers
- Implement temporary measure for backwards compatibility - "fake" VOEvent file text in response
- Add superevent categories
2.0.0.dev0
----------
:Date: June 28, 2018
- Identical to 1.29.dev1 other than packaging changes, but it was decided after the fact that we should bump the major version number
1.29.dev1
---------
:Date: June 21, 2018
- More new features for creating and managing superevents
1.29.dev0
---------
:Date: May 31, 2018
- New features for creating and managing superevents
1.28
----
:Date: April 24, 2018
- Various fixes for Python 3
1.27
----
:Date: February 13, 2018
- Change ``DEFAULT_SERVICE_URL`` used by command-line client to match other instances
- Update organization of full unit test suite
1.26
----
:Date: December 1, 2017
- Significant restructuring of unit tests
- Add several unit tests
- Update :py:meth:`ligo.gracedb.rest.GraceDb.createEvent` method to properly handle multiple labels and to work with upcoming server code changes
- Fix whitespace issues
1.25
----
:Date: August 2, 2017
- Fix packages ``provide``, ``requirements``, and build dependencies
- Add ability to create events with labels to the command-line client
- Add ability to set offline parameter with the command-line client
- Update unit tests
1.24
----
:Date: May 25, 2017
- Add a check on .netrc file permissions
- Add capability to create events with labels attached
- Add offline boolean parameter when creating events
1.23
----
:Date: February 3, 2017
- Improve exception handling and display of tracebacks in REST client
- Catch and handle exceptions in logging handler
- Update of dependencies
1.22
----
:Date: January 10, 2017
- Fix bug related to decoding logs
- Improve log handler cleanup
- Remove calls to ``sys.exit()`` from :py:mod:`ligo.gracedb.rest`
1.21
----
:Date: December 13, 2016
- Modernize Debian packaging and port to Python 2 and 3
- Make logging handler non-blocking
1.20
----
:Date: February 11, 2016
- Improve error handling for expired or missing credentials
- Improvederror handling when server returns non-JSON response
- Added ``--use-basic-auth`` option to command-line client
1.19.1
------
:Date: October 22, 2015
- Force TLSv1 for Python versions less than 2.7.9
- Change ``ligo.gracedb.rest.GraceDb.adjustResponse()`` to put retry-after in the JSON response for 429 respose codes
- Changed test service URL to gracedb-test.ligo.org
- Introduced wait time to test suite
1.19
----
:Date: July 29, 2015
- Bugfixes: comma separated strings for EM Observations and CLI ``createLog`` call
- Capture of additional kwargs to facilitate HardwareInjection event upload
- Packaging improvements (ligo as namespace package)
1.18
----
:Date: May 13, 2015
- Add comment to EM Observation record
- Allow Python lists as arguments to writeEMObservation
- Changed ligo to namespace package
1.18.dev0
---------
:Date: April 20, 2015
- New features for robotic basic auth
- New features for EM observation records
1.17
----
:Date: March 25, 2015
- Bugfix for Python version incompatibility in 1.16
- New methods/tests for creating and retrieving VOEvents
- Bugfix for gittag test
1.16
----
:Date: February 11, 2015
- Fixes for glue 1.47 to the command line client
- Use SSLContext and explicitly turn off client-side server verification
- Fix for command that lists groups, pipelines, and searches
- Allow multiple tags to be added to an event log at creation time
- Updates to unit test data
1.15
----
:Date: October 31, 2015
- Features for EMBB Event Log upload and retrieval
- Changes for (Group,Type) -> (Group,Pipeline,Search) transition
- Added docstrings
1.14
----
:Date: December 18, 2013
- Fixed 10 and 1000 event limits. Corresponds to issues 986 and 787 (on redmine page)
1.13
----
:Date: June 28, 2013
- Fixed renegotiation regression. Corresponds to issue 951 (on redmine page)
1.12
----
:Date: June 27, 2013
- Changed client to use REST API exclusively
- Extended REST API to include all API functionality
1.11
----
:Date: January 24, 2013
- Re-add ``--with python2`` to match other ligo-* Python modules
- Fix bug where stdin is specified, it is not actually read
- Add python-ligo-common to dependencies
1.10
----
:Date: January 18, 2013
- CLI replace feature had subtle openssl bug; now using REST client
- Typo in help text
- Typo in test.py wrt CWB test data
- Remove ``--with-python2`` from debian/rules
1.9
---
:Date: January 16, 2013
- Add slot feature to command line interface
- Add unit tests for CLI slot feature
- Add rudimentary test code documentation
1.8
---
:Date: January 4, 2013
- Incorporate Leo's patch for fixing import problem
1.7
---
:Date: December 21, 2012
- Add workaround for Python bug http://bugs.python.org/issue11898
- Add Leo Singer's convenience classes for logging
1.6
--
:Date: December 19, 2012
- Fix some typos
- Add more unit tests for GraceDb class
- Add test script for command line client
- Improve unit tests' usability
1.5
---
:Date: December 12, 2012
- Source 3.0 format
- Add support for REST API
- Add unit tests and test data
1.4
---
:Date: July 19, 2012
- Fixed SSL renegotiation bug on large file upload.
1.3
---
:Date: June 14, 2012
- Replace simplejson with cjson because simplejson is not available everywhere in the LSC
1.2
---
:Date: June 11, 2012
- Add file download command
1.1
---
:Date: January 22, 2012
- Bug Fix.
1.0
---
:Date: November 1, 2011
- Initial release
Command-line interface
======================
A command-line tool (``gracedb``) is provided which reproduces some of the functionality of the Python module.
This tool is most useful for small-scale manual work and it is not recommended to be used in a programmatic fashion.
This section will provide some information about what functionality is available, but detailed information about the available commands and their arguments is provided in the internal documentation.
This documentation can be accessed by:
- ``gracedb --help``
- ``gracedb <command> --help``
- ``gracedb <command> <subcommand> --help``
Credentials
-----------
The command-line tool will look up credentials in some expected locations by default, just as the client class :py:class:`ligo.gracedb.rest.GraceDb` does.
You can also provide credentials to the command-line interface by using the ``--creds`` argument or the ``--username`` and ``--password`` arguments, or by setting environment variables as detailed in the reference for :py:class:`ligo.gracedb.rest.GraceDb`.
Events
------
- Create an event: ``gracedb create event``
- Search for events: ``gracedb search events``
- Retrieve an individual event: ``gracedb get event``
- Update an event: ``gracedb update event``
Superevents
-----------
- Create a superevent: ``gracedb create superevent``
- Search for superevents: ``gracedb search superevents``
- Retrieve an individual superevent: ``gracedb get superevent``
- Update a superevent: ``gracedb update superevent``
- Confirm a superevent as GW: ``gracedb confirm_as_gw``
- Expose a superevent to the public: ``gracedb expose``
- Make a superevent internal-only: ``gracedb hide``
- Add an event to a superevent: ``gracedb add event``
- Remove an event from a superevent: ``gracedb remove event``
- Show allowed superevent categories: ``gracedb show superevent_categories``
Annotations
-----------
Log entries
~~~~~~~~~~~
- Create a log entry (with optional file upload): ``gracedb create log``
- List all log entries for an event or superevent: ``gracedb list logs``
- Get a specific log entry: ``gracedb get log``
Files
~~~~~
- Upload a file: ``gracedb create log``
- Get a list of files associated with an event or superevent: ``gracedb list files``
- Download a file: ``gracedb get file``
VOEvents
~~~~~~~~
- Create a VOEvent: ``gracedb create voevent``
- List VOEvents for an event or superevent: ``gracedb list voevents``
- Get a specific VOEvent: ``gracedb get voevent``
- Show allowed VOEvent types: ``gracedb show voevent_types``
EM observations
~~~~~~~~~~~~~~~
- Upload EM observation data: ``gracedb create emobservation``
- List all EM observations for an event or superevent: ``gracedb list emobservations``
- Get a specific EM observation: ``gracedb get emobservation``
- Show EM groups for which data can be uploaded: ``gracedb show emgroups``
Signoffs
~~~~~~~~
- Create a superevent signoff: ``gracedb create signoff``
- Update a superevent signoff: ``gracedb update signoff``
- Delete a superevent signoff: ``gracedb delete signoff``
- List all signoffs for a superevent: ``gracedb list signoffs``
- Get a specific signoff: ``gracedb get signoff``
- Show a list of allowed signoff types: ``gracedb show signoff_types``
- Show a list of allowed signoff statuses: ``gracedb show signoff_statuses``
Labels
~~~~~~
- List which labels are available on the server: ``gracedb show labels``
- Add a label to an event or superevent: ``gracedb add label``
- Remove a label from an event or superevent: ``gracedb remove label``
- Get a list of labels associated with an event or superevent: ``gracedb list labels``
- Get a specific label instance: ``gracedb get label``
Tags
~~~~
- Add a tag to a log entry: ``gracedb add tag``
- Remove a tag from a log entry: ``gracedb remove tag``
Other
-----
- Check your connection to the server: ``gracedb ping``
- Show the credentials that the client is using: ``gracedb credentials client``
- Show the user account the server has connected your credentials with: ``gracedb credentials server``
- Show analysis groups: ``gracedb show groups``
- Show analysis pipelines: ``gracedb show pipelines``
- Show search types: ``gracedb show searches``
- Show instruments: ``gracedb show instruments``
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import os
import importlib
from subprocess import check_output
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
def get_setup_output(*args):
cwd = os.path.join('..', '..')
return check_output((sys.executable, 'setup.py') + args, cwd=cwd).decode()
# -- Project information -----------------------------------------------------
project = get_setup_output('--name')
author = get_setup_output('--author')
# The short X.Y version
version = release = get_setup_output('--version')
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosectionlabel',
'sphinx.ext.napoleon',
'sphinx.ext.coverage',
]
# Define links in epilog
rst_epilog = """
.. |gracedb| replace:: GraceDB
.. _GraceDB: https://gracedb.ligo.org/
.. _pip: https://pip.pypa.io/en/stable/
"""
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
html_static_path = []
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'ligo-gracedbdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, project + '.tex', project + ' Documentation',
author, 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, project.lower(), project + ' Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, project, project + ' Documentation',
author, project, 'One line description of project.',
'Miscellaneous'),