gwdetchar.io.html module

Utilties for HTML output

class gwdetchar.io.html.FancyPlot(img, caption=None)

Bases: object

A helpful class of objects that coalesce image links and caption text for fancybox figures.

Parameters:

imgstr or FancyPlot

either a filename (including relative or absolute path) or another FancyPlot instance

captionstr

the text to be displayed in a fancybox as this figure’s caption

__dict__ = mappingproxy({'__module__': 'gwdetchar.io.html', '__doc__': "A helpful class of objects that coalesce image links and caption text\n    for fancybox figures.\n\n    Parameters\n    ----------\n    img : `str` or `FancyPlot`\n        either a filename (including relative or absolute path) or another\n        FancyPlot instance\n\n    caption : `str`\n        the text to be displayed in a fancybox as this figure's caption\n    ", '__init__': <function FancyPlot.__init__>, '__str__': <function FancyPlot.__str__>, '__dict__': <attribute '__dict__' of 'FancyPlot' objects>, '__weakref__': <attribute '__weakref__' of 'FancyPlot' objects>, '__annotations__': {}})

__doc__ = "A helpful class of objects that coalesce image links and caption text\n    for fancybox figures.\n\n    Parameters\n    ----------\n    img : `str` or `FancyPlot`\n        either a filename (including relative or absolute path) or another\n        FancyPlot instance\n\n    caption : `str`\n        the text to be displayed in a fancybox as this figure's caption\n    "

__init__(img, caption=None)

__module__ = 'gwdetchar.io.html'

__str__()

Return str(self).

__weakref__

list of weak references to the object

gwdetchar.io.html._get_card_header(context)

Return the correct bootstrap-4 card-header class for the given context

gwdetchar.io.html.about_this_page(config, packagelist=True, prog=None)

Write a blurb documenting how a page was generated, including the command-line arguments and configuration files used

Parameters:

configstr, list, optional

the absolute path(s) to one or a number of INI files used in this process

packagelistbool, optional

boolean switch to include (True) or exclude (False) a comprehensive list of system packages

progstr, optional

name of the program which produced this page, defaults to the script run on the command-line

Returns:

pagepage

the HTML page to be inserted into the #main <div>.

gwdetchar.io.html.alert(text, context='info', dismiss=True)

Enclose text within a bootstrap dialog box

Parameters:

textstr or list of str

text to enclose within the box, if a list then each item will be rendered in a separate <p> tag

contextstr, optional

Bootstrap context type, default: info

dismissbool, optional

boolean switch to enable (True) or disable (False) a dismiss button, default: True

Returns:

pagepage

the rendered dialog box object

gwdetchar.io.html.cis_link(channel, **params)

Write a channel name as a link to the Channel Information System

Parameters:

channelstr

the name of the channel to link

**params

other HTML parmeters for the <a> tag

Returns:

htmlstr

gwdetchar.io.html.close_page(page, target, **kwargs)

Close an HTML document with markup then write to disk

This method writes the closing markup to complement the opening written by init_page, something like:

</div>
<footer>
    <!-- some stuff -->
</footer>
</body>
</html>

Parameters:

pagemarkup.page

the markup object to close

targetstr

the output filename for HTML

gwdetchar.io.html.download_btn(content, label='Download summary', btndiv='dropdown float-right d-none d-lg-block', btnclass='btn btn-outline-secondary dropdown-toggle')

Toggle download options with a Bootstrap button

Parameters:

contentlist of tuple of str

collection of (title, link) pairs to list

labelstr, optional

text appearing inside the button, default: Download summary

id_str, optional

unique HTML identifier for this button

btndivstr, optional

class name of the enclosing <div>, default: dropdown float-right d-none d-lg-block

btnclassstr, optional

class name of the Bootstrap button object, default: btn btn-secondary dropdown-toggle

Returns:

pagepage

fully rendered download button

gwdetchar.io.html.dropdown(text, links, active=None, class_='nav-link dropdown-toggle')

Construct a dropdown menu in bootstrap format

Parameters:

textstr

dropdown menu header

linkslist

list of (Link text, linkurl) tuples or dict of such tuples for grouped dropdowns

activeint or list of ints, optional

collection of links to make active, default: None

class_str, optional

object class of the dropdown menu, default: 'dropdown-toggle'

Returns:

pagepage

HTML element with the following grammar:

<a>text</a>
<ul>
    <li>link</li>
    <li>link</li>
</ul>

gwdetchar.io.html.dropdown_link(page, link, active=False, class_='')

Format links within a dropdown menu

Parameters:

pagepage

a page object to format in-place

linkpage or list

the link(s) to format

activebool, optional

boolean switch to enable (True) or disable (False) an active link, default: False

class_str, optional

object class of the link, default: ''

gwdetchar.io.html.fancybox_img(img, linkparams={}, lazy=False, **params)

Return the markup to embed an <img> in HTML

Parameters:

imgFancyPlot

a FancyPlot object containing the path of the image to embed and its caption to be displayed

linkparamsdict, optional

the HTML attributes for the <a> tag

lazybool, optional

whether to lazy-load the image, default: False

**params

the HTML attributes for the <img> tag

Returns:

pagepage

the markup object containing fancyplot HTML

gwdetchar.io.html.finalize_static_urls(static, base, cssfiles, jsfiles)

Finalise the necessary CSS and javascript files as URLS.

The method parses the lists of files given, copying any local files into static as necessary to create resolvable URLs to include in the HTML <head>.

Parameters:

staticstr

the target directory for the static files, will be created if necessary

basestr

the base directory of the website

cssfileslist of str

the list of CSS files to include

jsfileslist of str

the (complete) list of javascript files to include

Returns:

cssurlslist of str

the finalised list of CSS files

jsurlslist of str

the finalised list of javascript files

gwdetchar.io.html.get_brand(ifo, name, gps, about=None)

Return a brand for navigation bar formatting

Parameters:

ifostr

interferometer prefix for color-coding, e.g. 'L1'

namestr

name of the analysis, e.g. 'Scattering'

gpsfloat

GPS second of the analysis

aboutstr, optional

relative path to the about page for this analysis, default: None

Returns:

brandpage

the navbar brand page object

class_str

object class of the navbar

gwdetchar.io.html.get_command_line(language='bash', about=True, prog=None)

Render the command-line invocation used to generate a page

Parameters:

languagestr, optional

type of environment the code is run in, default: 'bash'

aboutbool, optional

whether this markup is for an ‘about’ page, default: True

progstr, optional

name of the program which produced this page, defaults to the script run on the command-line

Returns:

pagepage

fully rendered command-line arguments

gwdetchar.io.html.html_link(href, txt, target='_blank', **params)

Write an HTML <a> tag

Parameters:

hrefstr

the URL to point to

txtstr

the text for the link

targetstr, optional

the target of this link

**params

other HTML parameters for the <a> tag

Returns:

htmlstr

gwdetchar.io.html.navbar(links, class_='navbar navbar-expand-md fixed-top shadow-sm', brand=None, collapse=True)

Construct a navigation bar in bootstrap format

Parameters:

linkslist

list of either (text, URL) tuples or page objects. Tuples will be written in <a> tags while pages will be copied directly. Both will be enclosed in a <li> element inside the navbar

class_str, optional

navbar object class, default: 'navbar navbar-expand-md fixed-top'

brandstr, page, or list, optional

branding for the navigation bar, default: None

collapsebool, optional

whether to toggle all dropdown menus, default: True

Returns:

pagepage

navbar HTML page object

gwdetchar.io.html.new_bootstrap_page(base='.', path='.', lang='en', refresh=False, topbtn=True, navbar=None, **kwargs)

Create a new page with custom twitter bootstrap CSS and JS headers

Parameters:

basestr, optional

relative path to the base directory, default:

pathstr, optional

path to directory where the page is located, default:

langstr, optional

language of the page, default: en

refreshbool, optional

boolean switch to enable periodic page refresh, default: False

topbtnbool, optional

boolean switch to include or exclude a floating button that scrolls to the top of the page, default: True

navbarstr, optional

HTML enconding of a floating navbar, will be ignored if not given, default: None

Returns:

pagepage

a populated HTML page object, which can be appended to as desired

gwdetchar.io.html.package_list()

Get the list of packages installed alongside this one

Returns a list of dict

gwdetchar.io.html.package_table(h2='Environment', class_='table table-sm table-hover table-responsive', caption='Table of packages installed in the production environment', id_='package-table')

Write a table listing packages installed in the current environment

Parameters:

h2str, None, optional

the header for the HTML section

captionstr, None, optional

the <caption> for the package table

Returns:

htmlstr

an HTML table

gwdetchar.io.html.parameter_table(content=[], start=None, end=None, flag=None, id_='parameters', tableclass='table table-sm table-hover')

Render an informative section with run parameters in HTML

Parameters:

content: `list` of `tuple` of `str`

collection of parameters to list

startfloat

GPS start time of the analysis

endfloat

GPS end time of the analysis

flagstr, optional

name of a data-quality state flag required for this analysis

sectionstr, optional

text to label the section header (<h2>), default: Parameters

id_str, optional

unique HTML identifier for this section, default: parameters

tableclassstr, optional

the class for the summary <table>, defaults to a responsive Bootstrap table

Returns:

pagepage

fully rendered table of parameters

gwdetchar.io.html.render_code(code, language)

Render a block of code with syntax highlighting

Parameters:

codestr

a raw block of source code

languagestr

language the code is written in, e.g. 'python'

Returns:

codepage

fully rendered command-line call

gwdetchar.io.html.scaffold_omega_scans(times, channel, plot_durations=[1, 4, 16], scandir='.')

Preview a batch of omega scans in HTML

Parameters:

timeslist of float

a list of GPS times to scan

channelstr

name of the channel being scanned, e.g. H1:GDS-CALIB_STRAIN

plot_durationslist of int

list of plot durations in seconds, default: [1, 4, 16]

scandirstr

path to the directory containing omega scans, default:

Returns:

pagepage

rendered scaffold of omega scan plots

gwdetchar.io.html.scaffold_plots(plots, nperrow=3, lazy=True)

Embed a list of images in a bootstrap scaffold

Parameters:

plotlist of FancyPlot

the list of image paths to embed

nperrowint

the number of images to place in a row (on a desktop screen)

lazybool, optional

whether to lazy-load images, default: True

Returns:

pagepage

the markup object containing the scaffolded HTML

gwdetchar.io.html.table(headers, data, caption=None, separator='', id=None, **class_)

Write a <table> with one row of headers and many rows of data

Parameters:

headerslist

list of column header names

datalist of lists

list of column data lists, for m rows and n columns, this should have dimensions m x n

captionstr, optional

content for this table’s <caption>

**class_

class attribute declarations for each tag used in the table, any of table, thead, tbody, tr, th, td, caption

Returns:

tablepage

a formatted HTML page object containing the <table>

gwdetchar.io.html.write_flag_html(flag, span=None, id=0, parent='accordion', context='warning', title=None, plotdir=None, plot_func=<function plot_segments>, **kwargs)

Write HTML for data-quality flags

Parameters:

flagDataQualityFlag

the flag object to represent

spanSegment, optional

GPS start and stop time of flag duration

idint, optional

unique identifier for the flag, default: 0

parentstr, optional

HTML identifier of the parent object, default: accordion

contextstr, optional

Bootstrap context type, default: warning

titlestr, optional

title of the flag, defaults to flag.name

plotdirstr, optional

path to directory containing plots, required if plotting segments

plot_funcfunc, optional

function used to plot segments, default: plot_segments

**kwargsdict, optional

additional keyword arguments to plot_func

Returns:

pagepage

fully rendered HTML with a card object for the flag

gwdetchar.io.html.write_footer(about=None, link=None, issues=None, external=None)

Write a <footer> for a bootstrap page

Parameters:

aboutstr, optional

path of about page to link

linkNone or tuple, optional

tuple of package name, HTML link to source code, and host name (e.g. GitHub)

issuesstr, optional

HTML link to issue report page

externalstr, optional

additional footer link to an external page

Returns:

pagepage

the markup object containing the footer HTML