/dochub-prototype

DocHub prototype · www.lsst.io generator

Primary LanguagePythonOtherNOASSERTION

LSST DocHub Prototype

Python Package Index Travis CI build status

Prototype of LSST DocHub (www.lsst.io) as a static website generator.

The DocHub project is an effort to index LSST's meta information — such as documents, software, tickets, and conversations — to make them accessible from a single website and API. Read more about the DocHub concept in SQR-013: LSST DocHub Design.

Usage

#/usr/bin/env python
from dochubproto import DocHubProto

p = DocHubProto()
idx = p.render_index()

Configuration

DocHubProto uses the following environment variables:

  • KEEPER_URL (default https://keeper.lsst.codes).
  • LOGLEVEL (default WARNING).
  • TEMPLATE_DIR: directory containing Jinja2 templates (default templates).
  • UL_TEMPLATE_NAME: relative path to template for individual document items (default doclist.jinja2).
  • IDX_TEMPLATE_NAME: relative path to the index.html template (default index.jinja2).
  • MAX_DOCUMENT_DATA_AGE: maximum cache age in seconds of a document (default 3600).

DocHubProto API overview

  • check_state() returns one of:

    • STATE_EMPTY ('empty')
    • STATE_READY ('ready')
    • STATE_REFRESHING ('refreshing')
    • STATE_STALE ('stale')

    A document is 'stale' if it is older than MAX_DOCUMENT_DATA_AGE.

  • get_document_data() and get_fresh_document_data() return a dict whose keys are document sections (e.g. DMTN) and within each section, a list ordered by document handle (e.g. dmtn-038).

  • render() returns an HTML unordered list entity created from the document data, encoded as UTF-8.

  • render_index() returns an HTML document created from the document data, encoded as UTF-8.

  • debug(), info(), warning(), error(), and critical() each log a message at the specified level; it uses a structlog logger to log JSON output via apikit.