Added stub for BrookEngine documentation.
authorStanislaw Klekot <dozzie@jarowit.net>
Wed, 10 May 2017 20:20:08 +0000 (22:20 +0200)
committerStanislaw Klekot <dozzie@jarowit.net>
Wed, 10 May 2017 20:20:08 +0000 (22:20 +0200)
12 files changed:
doc/.gitignore [new file with mode: 0644]
doc/Makefile [new file with mode: 0644]
doc/bin/postprocess-manpages [new file with mode: 0755]
doc/conf.py [new file with mode: 0644]
doc/glossary.rst [new file with mode: 0644]
doc/index.rst [new file with mode: 0644]
doc/manpages/client.rst [new file with mode: 0644]
doc/manpages/daemon.rst [new file with mode: 0644]
doc/themes/poole/layout.html [new file with mode: 0644]
doc/themes/poole/static/default.css_t [new file with mode: 0644]
doc/themes/poole/static/sidebar.js [new file with mode: 0644]
doc/themes/poole/theme.conf [new file with mode: 0644]

diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644 (file)
index 0000000..306cc1c
--- /dev/null
@@ -0,0 +1,3 @@
+/doctrees
+/html
+/man
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644 (file)
index 0000000..0510573
--- /dev/null
@@ -0,0 +1,25 @@
+#!/usr/bin/make -f
+
+SPHINX_DOCTREE = doctrees
+SPHINX_SOURCE = .
+SPHINX_HTML = html
+SPHINX_MANPAGES = man
+
+#-----------------------------------------------------------------------------
+
+.PHONY: all doc html man clean
+
+all doc: html man
+
+html:
+       sphinx-build -b html -d $(SPHINX_DOCTREE) $(SPHINX_SOURCE) $(SPHINX_HTML)
+
+man:
+       sphinx-build -b man -d $(SPHINX_DOCTREE) $(SPHINX_SOURCE) $(SPHINX_MANPAGES)
+       bin/postprocess-manpages $(SPHINX_MANPAGES)/*.[1-8]
+
+clean:
+       rm -rf $(SPHINX_DOCTREE) $(SPHINX_MANPAGES) $(SPHINX_HTML)
+
+#-----------------------------------------------------------------------------
+# vim:ft=make
diff --git a/doc/bin/postprocess-manpages b/doc/bin/postprocess-manpages
new file mode 100755 (executable)
index 0000000..fa9f8d2
--- /dev/null
@@ -0,0 +1,38 @@
+#!/bin/sh
+#
+# Fix some formatting that Sphinx got wrong.
+#
+
+indent_code_blocks() {
+  awk '
+    $1 == ".SH" {sect = $2}
+    $0 == ".ft P" {indent = 0}
+    indent {$0 = "  " $0}
+    # all code blocks except in SYNOPSIS section
+    $0 == ".ft C" && sect != "SYNOPSIS" {indent = 1}
+    {print}
+  '
+}
+
+fix_manpage_references() {
+  # \fIfoo(1)\fR => \fIfoo\fR\|(1)
+  sed 's/\\fI\([^ ]*\)\(([1-8])\)\\fP/\\fI\1\\fR\\|\2/g'
+}
+
+fix_double_quotes_listing() {
+  # double quotes in .TP<nl>.B -> \(dq
+  awk '
+    $1 == ".TP" { list = 1 }
+    $1 == ".B" && list { gsub(/"/, "\\(dq") }
+    $1 != ".TP" { list = 0 }
+    {print}
+  '
+}
+
+for FILE in "$@"; do
+  cat "$FILE" | \
+    indent_code_blocks | \
+    fix_manpage_references | \
+    fix_double_quotes_listing > "$FILE.tmp"
+  mv -- "$FILE.tmp" "$FILE"
+done
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644 (file)
index 0000000..9affaee
--- /dev/null
@@ -0,0 +1,49 @@
+#-----------------------------------------------------------------------------
+#
+# Sphinx configuration for BrookEngine project
+#
+#-----------------------------------------------------------------------------
+
+project = u'BrookEngine'
+#copyright = u'...'
+
+release = '0.0.0'
+version = '0.0'
+
+#-----------------------------------------------------------------------------
+
+# minimal Sphinx version
+#needs_sphinx = '1.0'
+
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']
+
+master_doc = 'index'
+source_suffix = '.rst'
+exclude_trees = ['html', 'man']
+
+#-----------------------------------------------------------------------------
+# HTML output
+#-----------------------------------------------------------------------------
+
+html_theme = 'poole'
+html_theme_path = ['themes']
+
+pygments_style = 'sphinx'
+
+#html_static_path = ['static']
+
+#-----------------------------------------------------------------------------
+# TROFF/man output
+#-----------------------------------------------------------------------------
+
+man_pages = [
+    ('manpages/client', 'brook', 'BrookEngine client',
+     [], 1),
+    ('manpages/daemon', 'brookengine', 'BrookEngine daemon',
+     [], 8),
+]
+
+#man_show_urls = False
+
+#-----------------------------------------------------------------------------
+# vim:ft=python
diff --git a/doc/glossary.rst b/doc/glossary.rst
new file mode 100644 (file)
index 0000000..3b0c140
--- /dev/null
@@ -0,0 +1,6 @@
+********
+Glossary
+********
+
+**TODO**
+
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644 (file)
index 0000000..167a8a4
--- /dev/null
@@ -0,0 +1,32 @@
+***********
+BrookEngine
+***********
+
+BrookEngine is a stream processing engine designed facilitate building
+monitoring systems. BrookEngine works as a data market, a place for monitoring
+probes to submit check results and metrics to and for processing clients to
+receive data from. BrookEngine operates in publish-subscribe model, so
+any additional tool can be plugged in easily.
+
+BrookEngine is part of a larger project `Seismometer
+<http://seismometer.net/>`_, monitoring system of modern architecture and
+flexibility.
+
+
+Table of contents
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   manpages/daemon
+   manpages/client
+   glossary
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+
diff --git a/doc/manpages/client.rst b/doc/manpages/client.rst
new file mode 100644 (file)
index 0000000..b9f4c50
--- /dev/null
@@ -0,0 +1,45 @@
+******************
+BrookEngine client
+******************
+
+Synopsis
+========
+
+.. code-block:: none
+
+    <data-generator> | brook --sender [--send-address=<addr>]
+    brook --reader [--read-address=<addr>] | <data-reader>
+    brook --exec [--reader] [--sender] [options] -- <command> <args> ...
+
+Description
+===========
+
+:program:`brook` is a command line client for BrookEngine.
+
+Usage
+=====
+
+Modes: {*stdio*, *exec*}x{*reader*, *sender*}
+
+:envvar:`$BROOK_SEND_ADDRESS`, :envvar:`$BROOK_READ_ADDRESS`
+
+Options
+-------
+
+.. program:: brook
+
+.. option:: --exec
+
+.. option:: --sender
+
+.. option:: --reader
+
+.. option:: --send-address <host>:<port>
+
+.. option:: --read-address <host>:<port>
+
+See Also
+========
+
+* :manpage:`brookengine(8)`
+* Seismometer <http://seismometer.net/>
diff --git a/doc/manpages/daemon.rst b/doc/manpages/daemon.rst
new file mode 100644 (file)
index 0000000..afcf476
--- /dev/null
@@ -0,0 +1,78 @@
+******************
+BrookEngine daemon
+******************
+
+Synopsis
+========
+
+.. code-block:: none
+
+    brookengine [options]
+    brookengine [--socket=<path>] reload
+    brookengine [--socket=<path>] list
+    brookengine [--socket=<path>] start <query>
+    brookengine [--socket=<path>] stop <query>
+    brookengine [--socket=<path>] restart <query>
+    brookengine [--socket=<path>] cancel-restart <query>
+
+Description
+===========
+
+BrookEngine is a data market for Seismometer monitoring system.
+
+Usage
+=====
+
+Something about queries.
+
+Ports: submission (MessagePack on port 5168), subscription (JSON/line on port
+5268).
+
+Files:
+
+* :file:`/etc/brookengine/brookengine.conf`
+* :file:`/etc/brookengine/queries.conf`
+* :file:`/etc/brookengine/queries.logging`
+* :file:`/etc/brookengine/plugin/`
+* :file:`/var/run/brookengine/queries`
+
+Commands
+--------
+
+Administrative commands.
+
+.. describe:: brookengine reload
+
+.. describe:: brookengine list
+
+.. describe:: brookengine start <query>
+
+.. describe:: brookengine stop <query>
+
+.. describe:: brookengine restart <query>
+
+.. describe:: brookengine cancel-restart <query>
+
+Options
+-------
+
+.. program:: brookengine
+
+.. option:: --socket <path>
+
+.. option:: --config <path>
+
+.. option:: --plugins <path>
+
+.. _brookengine-config:
+
+Configuration
+=============
+
+**TODO**
+
+See Also
+========
+
+* :manpage:`brook(1)`
+* Seismometer <http://seismometer.net/>
diff --git a/doc/themes/poole/layout.html b/doc/themes/poole/layout.html
new file mode 100644 (file)
index 0000000..d91a565
--- /dev/null
@@ -0,0 +1,14 @@
+{#
+    default/layout.html
+    ~~~~~~~~~~~~~~~~~~~
+
+    Sphinx layout template for the default theme.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{% extends "basic/layout.html" %}
+
+{% if theme_collapsiblesidebar|tobool %}
+{% set script_files = script_files + ['_static/sidebar.js'] %}
+{% endif %}
diff --git a/doc/themes/poole/static/default.css_t b/doc/themes/poole/static/default.css_t
new file mode 100644 (file)
index 0000000..b86a920
--- /dev/null
@@ -0,0 +1,284 @@
+/*
+ * default.css_t
+ * ~~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- default theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+    font-family: sans-serif;
+    font-size: 100%;
+    background-color: #ffffff;
+    color: #000000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    background-color: #ffffff;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin-top: 0;
+    margin-bottom: 0;
+    margin-right: {{ theme_sidebarwidth|toint }}px;
+    margin-left:  {{ theme_sidebarwidth|toint }}px;
+}
+
+div.body {
+    background-color: #ffffff;
+    color: #2e3436;
+    padding: 0 20px 30px 20px;
+    width: 800px; /* website: <body> */
+    margin: 1em auto;
+}
+
+{%- if theme_rightsidebar|tobool %}
+div.bodywrapper {
+    margin: 0 {{ theme_sidebarwidth|toint }}px 0 0;
+}
+{%- endif %}
+
+div.footer {
+    color: #bebebe;
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.footer a {
+    color: #bebebe;
+    text-decoration: underline;
+}
+
+div.related {
+    background-color: #ffffff;
+    line-height: 30px;
+    color: #2e3436;
+}
+
+div.related a {
+    color: #2e3436;
+}
+
+div.sphinxsidebar {
+    {%- if theme_stickysidebar|tobool %}
+    top: 30px;
+    bottom: 0;
+    margin: 0;
+    position: fixed;
+    overflow: auto;
+    height: auto;
+    {%- endif %}
+    {%- if theme_rightsidebar|tobool %}
+    float: right;
+    {%- if theme_stickysidebar|tobool %}
+    right: 0;
+    {%- endif %}
+    {%- endif %}
+    background-color: #eeeeec;
+}
+
+{%- if theme_stickysidebar|tobool %}
+/* this is nice, but it it leads to hidden headings when jumping
+   to an anchor */
+/*
+div.related {
+    position: fixed;
+}
+
+div.documentwrapper {
+    margin-top: 30px;
+}
+*/
+{%- endif %}
+
+div.sphinxsidebar h3 {
+    font-family: sans-serif;
+    color: #2e3436;
+    font-size: 1.4em;
+    font-weight: normal;
+    margin: 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h3 a {
+    color: #2e3436;
+}
+
+div.sphinxsidebar h4 {
+    font-family: sans-serif;
+    color: #2e3436;
+    font-size: 1.3em;
+    font-weight: normal;
+    margin: 5px 0 0 0;
+    padding: 0;
+}
+
+div.sphinxsidebar p {
+    color: #2e3436;
+}
+
+div.sphinxsidebar p.topless {
+    margin: 5px 10px 10px 10px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px;
+    padding: 0;
+    color: #2e3436;
+}
+
+div.sphinxsidebar a {
+    color: #2e3436; /* TODO: change the colour */
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #2e3436; /* TODO: change the colour */
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+{% if theme_collapsiblesidebar|tobool %}
+/* for collapsible sidebar */
+div#sidebarbutton {
+    background-color: {{ theme_sidebarbtncolor }}; /* #2e3436? */
+}
+{% endif %}
+
+/* -- hyperlink styles ------------------------------------------------------ */
+
+a {
+    color: #2f2f99;
+}
+
+a:visited {
+    color: #662f99;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 160%; }
+div.body h3 { font-size: 140%; }
+div.body h4 { font-size: 120%; }
+div.body h5 { font-size: 110%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: #000000;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: #000000;
+    color: #ffffff;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: justify;
+    line-height: 130%;
+}
+
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.admonition p {
+    margin-bottom: 5px;
+}
+
+div.admonition pre {
+    margin-bottom: 5px;
+}
+
+div.admonition ul, div.admonition ol {
+    margin-bottom: 5px;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+
+p.admonition-title {
+    display: inline;
+}
+
+p.admonition-title:after {
+    content: ":";
+}
+
+pre {
+    border: dotted black 1px;
+    background: #eeeeec;
+    font-size: 0.95em;
+    padding: 1em;
+}
+
+tt {
+    background-color: #eeeeec;
+    padding: 0 1px 0 1px;
+    font-size: 0.95em;
+}
+
+th {
+    background-color: #eeeeec;
+}
+
+.warning tt {
+    background: #efc2c2;
+}
+
+.note tt {
+    background: #d6d6d6;
+}
+
+.viewcode-back {
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}
+
+/* -- other body styles ----------------------------------------------------- */
+
+dl.glossary dt {
+    font-weight: bold;
+    font-size: inherit;
+}
+
+/* vim:set ft=css: */
diff --git a/doc/themes/poole/static/sidebar.js b/doc/themes/poole/static/sidebar.js
new file mode 100644 (file)
index 0000000..a45e192
--- /dev/null
@@ -0,0 +1,151 @@
+/*
+ * sidebar.js
+ * ~~~~~~~~~~
+ *
+ * This script makes the Sphinx sidebar collapsible.
+ *
+ * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds
+ * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
+ * used to collapse and expand the sidebar.
+ *
+ * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
+ * and the width of the sidebar and the margin-left of the document
+ * are decreased. When the sidebar is expanded the opposite happens.
+ * This script saves a per-browser/per-session cookie used to
+ * remember the position of the sidebar among the pages.
+ * Once the browser is closed the cookie is deleted and the position
+ * reset to the default (expanded).
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+$(function() {
+  // global elements used by the functions.
+  // the 'sidebarbutton' element is defined as global after its
+  // creation, in the add_sidebar_button function
+  var bodywrapper = $('.bodywrapper');
+  var sidebar = $('.sphinxsidebar');
+  var sidebarwrapper = $('.sphinxsidebarwrapper');
+
+  // for some reason, the document has no sidebar; do not run into errors
+  if (!sidebar.length) return;
+
+  // original margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar expanded
+  var bw_margin_expanded = bodywrapper.css('margin-left');
+  var ssb_width_expanded = sidebar.width();
+
+  // margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar collapsed
+  var bw_margin_collapsed = '.8em';
+  var ssb_width_collapsed = '.8em';
+
+  // colors used by the current theme
+  var dark_color = $('.related').css('background-color');
+  var light_color = $('.document').css('background-color');
+
+  function sidebar_is_collapsed() {
+    return sidebarwrapper.is(':not(:visible)');
+  }
+
+  function toggle_sidebar() {
+    if (sidebar_is_collapsed())
+      expand_sidebar();
+    else
+      collapse_sidebar();
+  }
+
+  function collapse_sidebar() {
+    sidebarwrapper.hide();
+    sidebar.css('width', ssb_width_collapsed);
+    bodywrapper.css('margin-left', bw_margin_collapsed);
+    sidebarbutton.css({
+        'margin-left': '0',
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('»');
+    sidebarbutton.attr('title', _('Expand sidebar'));
+    document.cookie = 'sidebar=collapsed';
+  }
+
+  function expand_sidebar() {
+    bodywrapper.css('margin-left', bw_margin_expanded);
+    sidebar.css('width', ssb_width_expanded);
+    sidebarwrapper.show();
+    sidebarbutton.css({
+        'margin-left': ssb_width_expanded-12,
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('«');
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    document.cookie = 'sidebar=expanded';
+  }
+
+  function add_sidebar_button() {
+    sidebarwrapper.css({
+        'float': 'left',
+        'margin-right': '0',
+        'width': ssb_width_expanded - 28
+    });
+    // create the button
+    sidebar.append(
+        '<div id="sidebarbutton"><span>&laquo;</span></div>'
+    );
+    var sidebarbutton = $('#sidebarbutton');
+    light_color = sidebarbutton.css('background-color');
+    // find the height of the viewport to center the '<<' in the page
+    var viewport_height;
+    if (window.innerHeight)
+         viewport_height = window.innerHeight;
+    else
+         viewport_height = $(window).height();
+    sidebarbutton.find('span').css({
+        'display': 'block',
+        'margin-top': (viewport_height - sidebar.position().top - 20) / 2
+    });
+
+    sidebarbutton.click(toggle_sidebar);
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    sidebarbutton.css({
+        'color': '#FFFFFF',
+        'border-left': '1px solid ' + dark_color,
+        'font-size': '1.2em',
+        'cursor': 'pointer',
+        'height': bodywrapper.height(),
+        'padding-top': '1px',
+        'margin-left': ssb_width_expanded - 12
+    });
+
+    sidebarbutton.hover(
+      function () {
+          $(this).css('background-color', dark_color);
+      },
+      function () {
+          $(this).css('background-color', light_color);
+      }
+    );
+  }
+
+  function set_position_from_cookie() {
+    if (!document.cookie)
+      return;
+    var items = document.cookie.split(';');
+    for(var k=0; k<items.length; k++) {
+      var key_val = items[k].split('=');
+      var key = key_val[0];
+      if (key == 'sidebar') {
+        var value = key_val[1];
+        if ((value == 'collapsed') && (!sidebar_is_collapsed()))
+          collapse_sidebar();
+        else if ((value == 'expanded') && (sidebar_is_collapsed()))
+          expand_sidebar();
+      }
+    }
+  }
+
+  add_sidebar_button();
+  var sidebarbutton = $('#sidebarbutton');
+  set_position_from_cookie();
+});
diff --git a/doc/themes/poole/theme.conf b/doc/themes/poole/theme.conf
new file mode 100644 (file)
index 0000000..5b78811
--- /dev/null
@@ -0,0 +1,9 @@
+[theme]
+inherit = basic
+stylesheet = default.css
+pygments_style = sphinx
+
+[options]
+rightsidebar = false
+stickysidebar = false
+collapsiblesidebar = false