From d4feaf2b49a8e1b6dca09054f06859160a4f6f8d Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 14:40:21 -0500 Subject: [PATCH 01/11] Update badges in README.rst --- README.rst | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 69cb683..9f28354 100644 --- a/README.rst +++ b/README.rst @@ -1,24 +1,27 @@ -HVeto is a python implementation of the HierarchicalVeto algorithm. It is +================= +Hierarchical Veto +================= + +Hveto is a python implementation of the HierarchicalVeto algorithm. It is a package designed for for gravitational-wave detector characterisation and data quality. -|PyPI version| |DOI| |License| |Supported Python versions| +The Hveto algorithm is fully described in `Smith et al. 2011`_ +(Classical and Quantum Gravity). + +|PyPI version| |Conda version| -|Build Status| |Coverage Status| +|DOI| |License| |Supported Python versions| ------- -Method ------- +|Build Status| |Coverage Status| |Documentation Status| -The HVeto algorithm is fully described in `Smith et al. 2011`_ -(Classical and Quantum Gravity). `Documentation`_ for running HVeto -is also available, but requires LIGO.ORG credentials. +https://hveto.readthedocs.io ------------ Installation ------------ -HVeto is best installed with `conda`_: +Hveto is best installed with `conda`_: .. code:: bash @@ -47,10 +50,11 @@ proposing additions/changes. .. _conda: https://conda.io .. _pip: https://pip.pypa.io/en/stable/ .. _Smith et al. 2011: //dx.doi.org/10.1088/0264-9381/28/23/235005 -.. _Documentation: https://ldas-jobs.ligo.caltech.edu/~duncan.macleod/hveto/latest/ .. |PyPI version| image:: https://badge.fury.io/py/hveto.svg :target: http://badge.fury.io/py/hveto +.. |Conda version| image:: https://img.shields.io/conda/vn/conda-forge/hveto.svg + :target: https://anaconda.org/conda-forge/hveto/ .. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/2584615.svg :target: https://doi.org/10.5281/zenodo.2584615 .. |License| image:: https://img.shields.io/pypi/l/hveto.svg @@ -61,3 +65,5 @@ proposing additions/changes. :target: https://travis-ci.org/gwdetchar/hveto .. |Coverage Status| image:: https://codecov.io/gh/gwdetchar/hveto/branch/master/graph/badge.svg :target: https://codecov.io/gh/gwdetchar/hveto +.. |Documentation Status| image:: https://readthedocs.org/projects/hveto/badge/?version=stable + :target: https://hveto.readthedocs.io/en/stable/?badge=stable From ba6db61fffef9fc9a9433203eb2df04204a83d88 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 15:46:14 -0500 Subject: [PATCH 02/11] Update and enhance documentation for use on readthedocs.io --- .readthedocs.yml | 30 ++++++++ README.rst | 2 +- bin/hveto-cache-events | 2 +- bin/hveto-trace | 5 +- docs/command-line/index.rst | 69 ++++++++++++----- docs/conf.py | 143 ++++++++++++++++++++---------------- docs/index.rst | 107 +++++++++++++++++++-------- docs/requirements.txt | 3 + 8 files changed, 245 insertions(+), 116 deletions(-) create mode 100644 .readthedocs.yml create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..ccd3b91 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,30 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Build docs in additional formats +formats: all + +# include submodules +submodules: + include: all + +# Set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: docs/requirements.txt + - requirements: requirements.txt + - method: setuptools + path: . + - method: pip + path: . + extra_requirements: + - docs diff --git a/README.rst b/README.rst index 9f28354..4e3644c 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ Hierarchical Veto ================= Hveto is a python implementation of the HierarchicalVeto algorithm. It is -a package designed for for gravitational-wave detector characterisation and +a package designed for gravitational-wave detector characterisation and data quality. The Hveto algorithm is fully described in `Smith et al. 2011`_ diff --git a/bin/hveto-cache-events b/bin/hveto-cache-events index 7b9bcbd..43d87d5 100644 --- a/bin/hveto-cache-events +++ b/bin/hveto-cache-events @@ -17,7 +17,7 @@ # You should have received a copy of the GNU General Public License # along with hveto. If not, see . -"""Create a (temporary) cache of event triggers for analysis by `hveto` later +"""Create a (temporary) cache of event triggers for analysis by `hveto` This method will apply the minimal SNR thresholds and any frequency cuts as given in the configuration files diff --git a/bin/hveto-trace b/bin/hveto-trace index f18d1ee..2cad097 100644 --- a/bin/hveto-trace +++ b/bin/hveto-trace @@ -16,8 +16,9 @@ # # You should have received a copy of the GNU General Public License # along with hveto. If not, see . -# """Check if a trigger was vetoed by a specified hveto run. -# """ + +"""Check if a trigger was vetoed by a specified hveto run +""" import os import sys diff --git a/docs/command-line/index.rst b/docs/command-line/index.rst index d62dc1f..b47f9f9 100644 --- a/docs/command-line/index.rst +++ b/docs/command-line/index.rst @@ -1,22 +1,23 @@ .. _command-line: -##################################### -Running ``hveto`` on the command line -##################################### +################### +On the command-line +################### -As described on the home page, the main interface to the hveto algorithm is the command-line executable ``hveto``. +The main interface to the Hveto algorithm is the command-line executable ``hveto``. Basic instructions ================== -Basic instructions on running ``hveto`` can be gained by looking at the ``--help`` menu: +For a full explanation of the available command-line arguments and options, you can run .. command-output:: hveto --help Detailed instructions ===================== -A few of the command-line options require special formatting, use the reference below for more detailed info. +A few of the command-line options require special formatting, which is detailed +in this section. ``gpsstart`` and ``gpsend`` --------------------------- @@ -35,43 +36,73 @@ will produce the same analysis as .. note:: - The quote marks used in the date string example are important so that the shell passes them to ``python`` as a single argument + It is important to use quote marks when passing date strings on the command-line. + This will ensure that the shell passes these to ``python`` as individual arguments. ``-j/--nproc`` -------------- -The majority of the processing time for ``hveto`` is taken up by two things +Wall-clock processing time for ``hveto`` is dominated by two things: -- reading event files for the auxiliary channels -- determining the most-significant channel for a given round +- Reading event files for the auxiliary channels +- Determining the most-significant channel for a given round -Each of these can be sped up by using multiple CPUs available on the host machine by supplying ``--nproc X`` where X is any integer. +Each of these can be sped up by using multiple CPUs on the host machine by +supplying ``--nproc X``, where ``X`` is any integer. .. warning:: - No restrictions are placed on the number of parallel processes that can be given on the command line, users should be aware that using too-high a number could overload the machine, or otherwise cause problems for themselves and other users. + Beware that using too many CPUs could overload the machine at runtime, + or otherwise cause problems for yourself and other users. - You can check how many processors are available on the machine with the following unix command + You can check how many processors are available with the following unix + command: - .. code-block:: bash + .. code:: bash cat /proc/cpuinfo | grep processor | wc -l ``-p/--primary-cache`` ---------------------- -This should receive a LAL-format cache file (see :mod:`glue.lal` for details) +This flag should receive a LAL-format cache file (see :mod:`glue.lal` for details). +If needed, you can use ``hveto-cache-events`` for this purpose (see below). ``-a/--auxiliary-cache`` ------------------------ -This should receive a LAL-format cache file (similarly to ``--primary-cache``), but with a specific format: +This flag requires a LAL-format cache file (similar to ``--primary-cache``), +but with a specific format: -- each contained trigger file should contain events for only a single channel -- the contained files should map to their channel as follows; if a channel is named ``X1:SYS-SUBSYS_NAME``, each filename should start ``X1-SYS_SUBSYS_NAME`` according to the `T050017 `_ convention. Additional underscore-delimited components can be given, but will not be used to map to the channel. +- Each trigger file should contain events for only a single channel +- The cached trigger files should map to their channel as follows: + if a channel is named ``X1:SYS-SUBSYS_NAME``, each filename should start + ``X1-SYS_SUBSYS_NAME`` according to the `T050017 `_ + convention. Additional underscore-delimited components can be given, + but will not be used to map to the channel. + +If needed, ``hveto-cache-events`` can be used to create this cache (see below). .. note:: - If the ``channels`` option is not given in the ``[auxiliary]`` section of the configuration, it will be populated from the unique list of channels parsed as above from the ``--auxiliary-cache`` + If ``channels`` is not given in the ``[auxiliary]`` section of the + configuration file, it will be populated from the unique list of channels + parsed from the ``--auxiliary-cache``. + +Caching trigger events +====================== + +The ``hveto-cache-events`` utility can be used to save both gravitational-wave +and auxiliary channel triggers: + +.. command-output:: hveto-cache-events --help + +Tracing event triggers +====================== + +The ``hveto-trace`` utility can be used to determine whether event triggers +are vetoed by a given ``hveto` run: + +.. command-output:: hveto-trace --help diff --git a/docs/conf.py b/docs/conf.py index 6397ec0..0df2f96 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # # Hveto documentation build configuration file, created by -# sphinx-quickstart on Thu Apr 21 14:05:08 2016. +# sphinx-quickstart on Wed Oct 28 15:22:25 2015. # # This file is execfile()d with the current directory set to its # containing dir. @@ -14,14 +14,11 @@ import sys import os +import glob +import sphinx_rtd_theme from hveto import __version__ as hveto_version -# 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. -sys.path.insert(0, os.path.abspath('.')) - # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -32,10 +29,11 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', - 'sphinx.ext.autosummary', 'numpydoc', 'sphinxcontrib.programoutput', ] @@ -43,9 +41,7 @@ # 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'] +# The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. @@ -56,24 +52,21 @@ # General information about the project. project = u'Hveto' -copyright = u'2016, Joshua Smith' -author = u'Joshua Smith' +copyright = u'2016, Josh Smith' +author = 'Josh Smith, Duncan Macleod, Alex Urban' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = hveto_version +version = '{0}.{1}'.format(*hveto_version.split('.')) # The full version, including alpha/beta/rc tags. release = hveto_version # 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 +#language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -83,15 +76,14 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +default_role = 'obj' # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). @@ -102,7 +94,7 @@ #show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'default' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] @@ -110,9 +102,6 @@ # If true, keep warnings as "system message" paragraphs in the built documents. #keep_warnings = False -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - # -- Options for HTML output ---------------------------------------------- @@ -126,11 +115,11 @@ #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -# The name for this set of Sphinx documents. -# " v documentation" by default. -#html_title = u'Hveto v0.1' +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -139,25 +128,24 @@ # of the sidebar. #html_logo = None -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # 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 = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. #html_extra_path = [] -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -#html_last_updated_fmt = None +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. @@ -196,24 +184,10 @@ # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - # Output file base name for HTML help builder. htmlhelp_basename = 'Hvetodoc' + # -- Options for LaTeX output --------------------------------------------- latex_elements = { @@ -225,17 +199,14 @@ # 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, 'Hveto.tex', u'Hveto Documentation', - u'Joshua Smith', 'manual'), + ('index', 'Hveto.tex', u'Hveto Documentation', + u'Josh Smith, Duncan Macleod, Alex Urban', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -264,8 +235,8 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'hveto', u'Hveto Documentation', - [author], 1) + ('index', 'hveto', u'Hveto Documentation', + [u'Josh Smith, Duncan Macleod, Alex Urban'], 1) ] # If true, show URL addresses after external links. @@ -278,9 +249,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'Hveto', u'Hveto Documentation', - author, 'Hveto', 'One line description of project.', - 'Miscellaneous'), + ('index', 'Hveto', u'Hveto Documentation', + u'Josh Smith, Duncan Macleod, Alex Urban', 'Hveto', 'One line description of project.', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. @@ -295,7 +266,6 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False -# -- Extensions ----------------------------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { @@ -303,5 +273,52 @@ 'numpy': ('http://docs.scipy.org/doc/numpy/', None), 'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None), 'matplotlib': ('http://matplotlib.sourceforge.net/', None), - 'gwpy': ('http://gwpy.github.io/docs/latest/', None), + 'astropy': ('http://docs.astropy.org/en/stable/', None), + 'gwpy': ('http://gwpy.github.io/docs/stable/', None), } + +# -- autosummary + +autosummary_generate = True + +# -- numpydoc + +# use blockquotes (numpydoc>=0.8 only) +numpydoc_use_blockquotes = True + + +# -- run sphinx-apidoc automatically ------------------------------------------ +# this is required to have apidoc generated as part of readthedocs builds +# see https://github.com/rtfd/readthedocs.org/issues/1139 + +def run_apidoc(_): + """Call sphinx-apidoc + """ + from sphinx.ext.apidoc import main as apidoc_main + curdir = os.path.abspath(os.path.dirname(__file__)) + apidir = os.path.join(curdir, 'api') + module = os.path.join(curdir, os.path.pardir, 'hveto') + apidoc_main([module, '--separate', '--force', '--output-dir', apidir]) + + +# -- add static files---------------------------------------------------------- + +def setup_static_content(app): + # configure stylesheets + for sdir in html_static_path: + # add stylesheets + cssdir = os.path.join(sdir, 'css') + for cssf in glob.glob(os.path.join(cssdir, '*.css')): + app.add_stylesheet(cssf.split(os.path.sep, 1)[1]) + + # add custom javascript + jsdir = os.path.join(sdir, 'js') + for jsf in glob.glob(os.path.join(jsdir, '*.js')): + app.add_javascript(jsf.split(os.path.sep, 1)[1]) + + +# -- setup -------------------------------------------------------------------- + +def setup(app): + setup_static_content(app) + app.connect('builder-inited', run_apidoc) diff --git a/docs/index.rst b/docs/index.rst index 2deb87e..7f634d3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,50 +1,71 @@ -.. Hveto documentation master file, created by - sphinx-quickstart on Thu Apr 21 14:05:08 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +================= +Hierarchical Veto +================= -Welcome to Hveto's documentation! -================================= +|PyPI version| |Conda version| -The HierarchichalVeto is an algorithm to identify statistically-significant correlations between transient noise events (triggers) in instrumental or environment data channels and those in the main calibrated gravitational-wave strain output for a ground-based laser interferometer gravitational-wave detector. -It is a key tool in reducing the noise background in searches for transient gravitational-wave signals, and was used during the detection of the binary black hole signal `GW150914 `_. +|DOI| |License| |Supported Python versions| -For full details see `Smith et al. (Classical and Quantum Gravity, 2011) `_ +|Build Status| |Coverage Status| |Documentation Status| -Installing Hveto ----------------- +Hveto is a package designed for gravitational-wave detector characterisation +and data quality. The algorithm identifies statistically significant +correlations between transient noise events (triggers) in instrumental or +environmental data channels, and those in the calibrated gravitational-wave +strain output. Hveto is a key tool in reducing the noise background in searches +for transient gravitational-wave signals, and was used, for example, during the +detection of the binary black hole signal +`GW150914 `_. -The easiest method to install hveto is using `pip `_ directly from the `GitHub repository `_: +For full details please refer to `Smith et al. 2011`_ +(Classical and Quantum Gravity). -.. code-block:: bash +To get started, simply import the core module: - $ pip install git+https://github.com/gwdetchar/hveto.git +.. code:: python -How to run Hveto ----------------- + import hveto -The main product of this package is the command-line executable `hveto`, which runs an end-to-end search for statistical coincidences, and produces a list of viable data-quality flags that can be used as vetoes in a search, as well as an HTML summary. +------------ +Installation +------------ -To run an analysis: +Hveto is best installed with `conda`_: -.. code-block:: bash +.. code:: bash - $ hveto --config-file ./my-config-file.ini + conda install -c conda-forge hveto -where ```` and ```` are the start and stop GPS times of the analysis period, and ``./my-config-file.ini`` is the path of your configuration file. Strictly speaking the configuration file is optional, but is highly recommend if you want to have any control over your analysis. +but can also be installed with `pip`_: -For a full list of command-line argument and options, run +.. code:: bash -.. code-block:: bash + python -m pip install hveto - $ hveto --help +------------ +Contributing +------------ -For more details see :ref:`command-line`. +All code should follow the Python Style Guide outlined in `PEP 0008`_; +users can use the `pep8`_ package to check their code for style issues +before submitting. -Package documentation ---------------------- +See `the contributions guide`_ for the recommended procedure for +proposing additions/changes. + +The Hveto project is hosted on GitHub: + +* Issue tickets: https://github.com/gwdetchar/hveto/issues +* Source code: https://github.com/gwdetchar/hveto + +License +------- -Please consult these pages for more details on using Hveto: +Hveto is distributed under the `GNU General Public License`_. + +===================== +Package documentation +===================== .. toctree:: :maxdepth: 1 @@ -52,9 +73,35 @@ Please consult these pages for more details on using Hveto: command-line/index api/hveto.config -Indices and tables -================== +======= +Sitemap +======= * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +.. _PEP 0008: https://www.python.org/dev/peps/pep-0008/ +.. _pep8: https://pypi.python.org/pypi/pep8 +.. _the contributions guide: https://github.com/gwdetchar/hveto/blob/master/CONTRIBUTING.md +.. _conda: https://conda.io +.. _pip: https://pip.pypa.io/en/stable/ +.. _Smith et al. 2011: //dx.doi.org/10.1088/0264-9381/28/23/235005 +.. _GNU General Public License: https://github.com/gwdetchar/hveto/blob/master/LICENSE + +.. |PyPI version| image:: https://badge.fury.io/py/hveto.svg + :target: http://badge.fury.io/py/hveto +.. |Conda version| image:: https://img.shields.io/conda/vn/conda-forge/hveto.svg + :target: https://anaconda.org/conda-forge/hveto/ +.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/2584615.svg + :target: https://doi.org/10.5281/zenodo.2584615 +.. |License| image:: https://img.shields.io/pypi/l/hveto.svg + :target: https://choosealicense.com/licenses/gpl-3.0/ +.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/hveto.svg + :target: https://pypi.org/project/hveto/ +.. |Build Status| image:: https://travis-ci.org/gwdetchar/hveto.svg?branch=master + :target: https://travis-ci.org/gwdetchar/hveto +.. |Coverage Status| image:: https://codecov.io/gh/gwdetchar/hveto/branch/master/graph/badge.svg + :target: https://codecov.io/gh/gwdetchar/hveto +.. |Documentation Status| image:: https://readthedocs.org/projects/hveto/badge/?version=stable + :target: https://hveto.readthedocs.io/en/stable/?badge=stable diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..43225a4 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +numpydoc +sphinx_rtd_theme +sphinxcontrib-programoutput From e6ce9dbf20822f4b868d5e47c9f2589f86f71c05 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 16:03:11 -0500 Subject: [PATCH 03/11] Add significantly enhanced documentation of hveto --- .gitignore | 5 ++++- docs/api/index.rst | 8 ++++++++ docs/command-line/index.rst | 36 ++++++++++++++++++------------------ docs/conf.py | 2 +- docs/index.rst | 1 + 5 files changed, 32 insertions(+), 20 deletions(-) create mode 100644 docs/api/index.rst diff --git a/.gitignore b/.gitignore index b2db3c3..714a942 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,10 @@ # documentation products /docs/_build/ -/docs/api/ +/docs/_templates/ +/docs/_static/ +/docs/api/modules.rst +/docs/api/hveto.* # test products /.cache/ diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..a69e68a --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,8 @@ +API +--- + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/docs/command-line/index.rst b/docs/command-line/index.rst index b47f9f9..cae584b 100644 --- a/docs/command-line/index.rst +++ b/docs/command-line/index.rst @@ -4,7 +4,7 @@ On the command-line ################### -The main interface to the Hveto algorithm is the command-line executable ``hveto``. +The main interface to the Hveto algorithm is the command-line executable `hveto`. Basic instructions ================== @@ -19,7 +19,7 @@ Detailed instructions A few of the command-line options require special formatting, which is detailed in this section. -``gpsstart`` and ``gpsend`` +`gpsstart` and `gpsend` --------------------------- Each of the required GPS start and stop times can be given as GPS integers, or as date strings, e.g. @@ -37,20 +37,20 @@ will produce the same analysis as .. note:: It is important to use quote marks when passing date strings on the command-line. - This will ensure that the shell passes these to ``python`` as individual arguments. + This will ensure that the shell passes these to `python` as individual arguments. -``-j/--nproc`` +`-j/--nproc` -------------- -Wall-clock processing time for ``hveto`` is dominated by two things: +Wall-clock processing time for `hveto` is dominated by two things: - Reading event files for the auxiliary channels - Determining the most-significant channel for a given round Each of these can be sped up by using multiple CPUs on the host machine by -supplying ``--nproc X``, where ``X`` is any integer. +supplying `--nproc X`, where `X` is any integer. .. warning:: @@ -64,37 +64,37 @@ supplying ``--nproc X``, where ``X`` is any integer. cat /proc/cpuinfo | grep processor | wc -l -``-p/--primary-cache`` +`-p/--primary-cache` ---------------------- This flag should receive a LAL-format cache file (see :mod:`glue.lal` for details). -If needed, you can use ``hveto-cache-events`` for this purpose (see below). +If needed, you can use `hveto-cache-events` for this purpose (see below). -``-a/--auxiliary-cache`` +`-a/--auxiliary-cache` ------------------------ -This flag requires a LAL-format cache file (similar to ``--primary-cache``), +This flag requires a LAL-format cache file (similar to `--primary-cache`), but with a specific format: - Each trigger file should contain events for only a single channel - The cached trigger files should map to their channel as follows: - if a channel is named ``X1:SYS-SUBSYS_NAME``, each filename should start - ``X1-SYS_SUBSYS_NAME`` according to the `T050017 `_ + if a channel is named `X1:SYS-SUBSYS_NAME`, each filename should start + `X1-SYS_SUBSYS_NAME` according to the `T050017 `_ convention. Additional underscore-delimited components can be given, but will not be used to map to the channel. -If needed, ``hveto-cache-events`` can be used to create this cache (see below). +If needed, `hveto-cache-events` can be used to create this cache (see below). .. note:: - If ``channels`` is not given in the ``[auxiliary]`` section of the + If `channels` is not given in the `[auxiliary]` section of the configuration file, it will be populated from the unique list of channels - parsed from the ``--auxiliary-cache``. + parsed from the `--auxiliary-cache`. Caching trigger events ====================== -The ``hveto-cache-events`` utility can be used to save both gravitational-wave +The `hveto-cache-events` utility can be used to save both gravitational-wave and auxiliary channel triggers: .. command-output:: hveto-cache-events --help @@ -102,7 +102,7 @@ and auxiliary channel triggers: Tracing event triggers ====================== -The ``hveto-trace`` utility can be used to determine whether event triggers -are vetoed by a given ``hveto` run: +The `hveto-trace` utility can be used to determine whether event triggers +are vetoed by a given `hveto` run: .. command-output:: hveto-trace --help diff --git a/docs/conf.py b/docs/conf.py index 0df2f96..e5cffac 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -136,7 +136,7 @@ # 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 = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/index.rst b/docs/index.rst index 7f634d3..ec8aca6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,6 +72,7 @@ Package documentation command-line/index api/hveto.config + api/index ======= Sitemap From 0a273f89a10979c8f6afbedc1c29a1ac5e1cc5cc Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 18:45:50 -0500 Subject: [PATCH 04/11] Remove header info about autogen, it's not correct --- docs/conf.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e5cffac..fb4972f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,8 +1,5 @@ # -*- coding: utf-8 -*- # -# Hveto documentation build configuration file, created by -# sphinx-quickstart on Wed Oct 28 15:22:25 2015. -# # This file is execfile()d with the current directory set to its # containing dir. # From 7759202d9a7555e698d1f2c4a37fece3d72e1a58 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 19:33:04 -0500 Subject: [PATCH 05/11] Cross-link to gwdetchar docs --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index fb4972f..3f154e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -272,6 +272,7 @@ 'matplotlib': ('http://matplotlib.sourceforge.net/', None), 'astropy': ('http://docs.astropy.org/en/stable/', None), 'gwpy': ('http://gwpy.github.io/docs/stable/', None), + 'gwdetchar': ('http://gwdetchar.readthedocs.io/en/stable', None), } # -- autosummary From 54d764b2d7a0b7a7d8b191d3d9782c35f48d1a12 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 19:36:55 -0500 Subject: [PATCH 06/11] Cross-link to gwsumm docs --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index 3f154e7..4823a86 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -273,6 +273,7 @@ 'astropy': ('http://docs.astropy.org/en/stable/', None), 'gwpy': ('http://gwpy.github.io/docs/stable/', None), 'gwdetchar': ('http://gwdetchar.readthedocs.io/en/stable', None), + 'gwsumm': ('http://gwsumm.readthedocs.io/en/stable', None), } # -- autosummary From ef7d5d85ddb6a551bd51c627610d8efac4a1d1b5 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 21:31:21 -0500 Subject: [PATCH 07/11] Use a bootstrap theme because it's closer to what our output pages look like --- docs/conf.py | 14 ++++++++++---- docs/index.rst | 8 -------- docs/requirements.txt | 2 +- 3 files changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 4823a86..2edecc3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,7 +12,7 @@ import sys import os import glob -import sphinx_rtd_theme +import sphinx_bootstrap_theme from hveto import __version__ as hveto_version @@ -104,15 +104,21 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +html_theme = 'bootstrap' # 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 = {} +html_theme_options = { + 'source_link_position': None, + 'navbar_site_name': "Contents", + 'navbar_sidebarrel': True, + 'navbar_pagenav': False, + 'bootswatch_theme': 'united', +} # Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/docs/index.rst b/docs/index.rst index ec8aca6..d2b8ac5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,6 @@ Hierarchical Veto |DOI| |License| |Supported Python versions| -|Build Status| |Coverage Status| |Documentation Status| - Hveto is a package designed for gravitational-wave detector characterisation and data quality. The algorithm identifies statistically significant correlations between transient noise events (triggers) in instrumental or @@ -100,9 +98,3 @@ Sitemap :target: https://choosealicense.com/licenses/gpl-3.0/ .. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/hveto.svg :target: https://pypi.org/project/hveto/ -.. |Build Status| image:: https://travis-ci.org/gwdetchar/hveto.svg?branch=master - :target: https://travis-ci.org/gwdetchar/hveto -.. |Coverage Status| image:: https://codecov.io/gh/gwdetchar/hveto/branch/master/graph/badge.svg - :target: https://codecov.io/gh/gwdetchar/hveto -.. |Documentation Status| image:: https://readthedocs.org/projects/hveto/badge/?version=stable - :target: https://hveto.readthedocs.io/en/stable/?badge=stable diff --git a/docs/requirements.txt b/docs/requirements.txt index 43225a4..dbbdab1 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ numpydoc -sphinx_rtd_theme +sphinx_bootstrap_theme sphinxcontrib-programoutput From c1c25192c381c122e936bf916bd506617f3ce023 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 21:42:54 -0500 Subject: [PATCH 08/11] Update .gitignore --- .gitignore | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 714a942..a0d60b5 100644 --- a/.gitignore +++ b/.gitignore @@ -11,8 +11,7 @@ # documentation products /docs/_build/ -/docs/_templates/ -/docs/_static/ +/docs/_generated/ /docs/api/modules.rst /docs/api/hveto.* From 131ad93d0dd413476abb111bf29fa1bf94f5bc2f Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Sun, 21 Apr 2019 21:47:23 -0500 Subject: [PATCH 09/11] Add a table-of-contents sidebar --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 2edecc3..89c9fec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -155,7 +155,7 @@ #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = {'**': ['localtoc.html', 'sourcelink.html', 'searchbox.html']} # Additional templates that should be rendered to pages, maps page names to # template names. From 7285bab09e8159dfaa3c6513c8e61b1592c45ff1 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Mon, 22 Apr 2019 01:50:02 -0500 Subject: [PATCH 10/11] Use Livingston-like color scheme for navigation --- docs/_static/css/custom.css | 216 ++++++++++++++++++++++++++++++++++++ docs/_static/hveto-docs.css | 13 --- docs/conf.py | 2 +- docs/index.rst | 13 +-- 4 files changed, 218 insertions(+), 26 deletions(-) create mode 100644 docs/_static/css/custom.css delete mode 100644 docs/_static/hveto-docs.css diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..8080b4f --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,216 @@ +/.text-primary { + color: #4ba6ff; +} + +.bg-primary { + background-color: #4ba6ff; +} + +.btn-primary { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +a.text-primary:hover, a.text-primary:focus { + color: #0080fe; +} + +a.bg-primary:hover, a.bg-primary:focus { + background-color: #0080fe; +} + +.btn-primary:focus, .btn-primary.focus { + background-color: #0080fe; + border-color: #0080fe; +} + +.btn-primary:hover { + background-color: #0080fe; + border-color: #0080fe; +} + +.btn-primary:active, .btn-primary.active, .open > .dropdown-toggle.btn-primary { + background-color: #0080fe; + border-color: #0080fe +} + +.navbar-default .navbar-nav > .active > a, .navbar-default .navbar-nav > .active > a:hover, +.navbar-default .navbar-nav > .active > a:focus { + background-color: #0080fe +} + +.navbar-default .navbar-nav > .open > a, .navbar-default .navbar-nav > .open > a:hover, +.navbar-default .navbar-nav > .open > a:focus { + background-color: #0080fe; +} + +.label-primary[href]:hover, .label-primary[href]:focus { + background-color: #0080fe +} + +a.text-primary:hover, a.text-primary:focus { + color: #0080fe +} + +a.bg-primary:hover, a.bg-primary:focus { + background-color: #0080fe +} + +.btn-primary:focus, .btn-primary.focus { + background-color: #0080fe; + border-color: #0080fe +} + +.btn-primary:hover { + background-color: #0080fe; + border-color: #0080fe +} + +.btn-primary:active, .btn-primary.active, .open > .dropdown-toggle.btn-primary { + background-color: #0080fe; + border-color: #0080fe +} + +.navbar-default .navbar-nav > .open > a, .navbar-default .navbar-nav > .open > a:hover, +.navbar-default .navbar-nav > .open > a:focus { + background-color: #0080fe; +} + + +.label-primary[href]:hover, .label-primary[href]:focus { + background-color: #0080fe +} + +.btn-primary.disabled:hover, .btn-primary[disabled]:hover, fieldset[disabled] .btn-primary:hover, +.btn-primary.disabled:focus, .btn-primary[disabled]:focus, fieldset[disabled] .btn-primary:focus, +.btn-primary.disabled.focus, .btn-primary[disabled].focus, fieldset[disabled] .btn-primary.focus { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.btn-primary .badge { + color: #4ba6ff; +} + +.btn-link { + color: #4ba6ff; +} + +.dropdown-menu > li > a:hover, .dropdown-menu > li > a:focus { + background-color: #4ba6ff; +} + +.dropdown-menu > .active > a, .dropdown-menu > .active > a:hover, .dropdown-menu > .active > a:focus { + background-color: #4ba6ff; +} + +.nav .open > a, .nav .open > a:hover, .nav .open > a:focus { + border-color: #4ba6ff; +} + +.nav-pills > li.active > a, .nav-pills > li.active > a:hover, .nav-pills > li.active > a:focus { + background-color: #4ba6ff; +} + +.navbar-default { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.navbar-default .navbar-nav > li > a:hover, .navbar-default .navbar-nav > li > a:focus { + background-color: #188dff; +} + +.navbar-default .navbar-toggle { + border-color: #188dff +} + +.navbar-default .navbar-toggle:hover, .navbar-default .navbar-toggle:focus { + background-color: #188dff +} + +@media (max-width:767px) { + .navbar-default .navbar-nav .open .dropdown-menu > li > a:hover, .navbar-default .navbar-nav .open .dropdown-menu > li > a:focus { + background-color: #188dff + } + + .navbar-default .navbar-nav .open .dropdown-menu > .active > a, .navbar-default .navbar-nav .open .dropdown-menu > .active > a:hover, + .navbar-default .navbar-nav .open .dropdown-menu > .active > a:focus { + background-color: #0080fe + } +} + +.pagination > li > a:hover, .pagination > li > span:hover, .pagination > li > a:focus, +.pagination > li > span:focus { + color: #188dff; +} + +a:hover, a:focus { + color: #188dff; +} + +.btn-link:hover, .btn-link:focus { + color: #188dff; +} + +.navbar-default .navbar-nav > li > a:hover, .navbar-default .navbar-nav > li > a:focus { + background-color: #188dff; +} + +.navbar-default .navbar-toggle { + border-color: #188dff; +} + +.navbar-default .navbar-collapse, .navbar-default .navbar-form { + border-color: #d34615 +} + +.pagination > li > a, .pagination > li > span { + color: #4ba6ff; +} + +.label-primary { + background-color: #4ba6ff; +} + +.list-group-item.active > .badge, .nav-pills > .active > a > .badge { + color: #4ba6ff; +} + +a.thumbnail:hover, a.thumbnail:focus, a.thumbnail.active { + border-color: #4ba6ff; +} + +.progress-bar { + background-color: #4ba6ff; +} + +.list-group-item.active, .list-group-item.active:hover, .list-group-item.active:focus { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.panel-primary { + border-color: #4ba6ff; +} + +.panel-primary > .panel-heading { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.panel-primary > .panel-heading + .panel-collapse > .panel-body { + border-top-color: #4ba6ff; +} + +.panel-primary > .panel-heading .badge { + color: #4ba6ff; +} + +.panel-primary > .panel-footer + .panel-collapse > .panel-body { + border-bottom-color: #4ba6ff; +} + +.navbar-default .badge { + color: #4ba6ff; +} diff --git a/docs/_static/hveto-docs.css b/docs/_static/hveto-docs.css deleted file mode 100644 index 795a077..0000000 --- a/docs/_static/hveto-docs.css +++ /dev/null @@ -1,13 +0,0 @@ -/* -- hveto documentation style --------------------------------------------- */ -/* just a few tweaks to the sphinx_rtd_theme styling */ - -/* override table width restrictions */ -.wy-table-responsive table td, .wy-table-responsive table th { - white-space: normal; -} - -.wy-table-responsive { - margin-bottom: 24px; - max-width: 100%; - overflow: visible; -} diff --git a/docs/conf.py b/docs/conf.py index 89c9fec..ddb61ec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,7 +57,7 @@ # built documents. # # The short X.Y version. -version = '{0}.{1}'.format(*hveto_version.split('.')) +version = hveto_version # The full version, including alpha/beta/rc tags. release = hveto_version diff --git a/docs/index.rst b/docs/index.rst index d2b8ac5..5e5a843 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,25 +61,14 @@ License Hveto is distributed under the `GNU General Public License`_. -===================== -Package documentation -===================== - .. toctree:: :maxdepth: 1 + :hidden: command-line/index api/hveto.config api/index -======= -Sitemap -======= - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - .. _PEP 0008: https://www.python.org/dev/peps/pep-0008/ .. _pep8: https://pypi.python.org/pypi/pep8 .. _the contributions guide: https://github.com/gwdetchar/hveto/blob/master/CONTRIBUTING.md From 48a0e748006b4ffc8ebc0b202261997567639003 Mon Sep 17 00:00:00 2001 From: Alex Urban Date: Mon, 22 Apr 2019 09:42:17 -0500 Subject: [PATCH 11/11] Minor edit: document LSCSoft conda builds --- docs/index.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 5e5a843..56c884e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,7 +15,7 @@ for transient gravitational-wave signals, and was used, for example, during the detection of the binary black hole signal `GW150914 `_. -For full details please refer to `Smith et al. 2011`_ +For full details about the algorithm, please refer to `Smith et al. 2011`_ (Classical and Quantum Gravity). To get started, simply import the core module: @@ -40,6 +40,11 @@ but can also be installed with `pip`_: python -m pip install hveto +Note, users with `LIGO.ORG` credentials have access to a software +container with a regularly-updated build of Hveto. For more +information please refer to the +`LSCSoft Conda `_ documentation. + ------------ Contributing ------------