diff options
Diffstat (limited to 'doc')
47 files changed, 2121 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..9826b9d --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Tipboard.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Tipboard.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Tipboard" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Tipboard" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/api.rst b/doc/api.rst new file mode 100644 index 0000000..50ae7e4 --- /dev/null +++ b/doc/api.rst @@ -0,0 +1,216 @@ +=== +API +=== + +One of the advantages of Tipboard is flexibility in feeding tiles with data. We +achieve that by providing a simple, REST API - that way, your feeding scripts +may be written in any language (Python, Ruby, Bash, Perl, PHP - you name it). +The only limitation is the format of input data accepted by a given tile type +(see :ref:`tiles_library` for the details). + +To experiment with resources specified below you can use tools like `Advanced +REST Client <http://chromerestclient.appspot.com/>`_ (Chrome extension), or +`cURL <http://curl.haxx.se/>`_, if you prefer working from command line. For +Python programmers, there's an excellent `Requests +<http://docs.python-requests.org/en/latest/>`_ library, which we strongly +recommend. + +.. _api_key: + +API key +------- + +To send anything to your tiles, first you have to get your API key. This unique +key is generated for you automatically during Tipboard's installation and may +be read in the ``~/.tipboard/settings-local.py`` file - it is a sequence of +characters starting with ``API_KEY``, e.g.:: + + API_KEY = 'e2c3275d0e1a4bc0da360dd225d74a43' + +If you can't see any such string, just add the key manually (it doesn't have +to be as long and hard to memorise as the one above, though). + +.. note:: + + Every change in ``settings-local.py`` file requires restart of the + application. + +Available resources +------------------- + +Current API version: **v0.1** + +.. note:: + + In 99% of cases, probably only ``push`` and ``tileconfig`` will be of + interest to you. + + +.. http:post:: /api/(api_version)/(api_key)/push + + Feeds tiles with data. Input data should be provided in the format that + complies with the one used in a desired tile. **Note:** a tile to which data + will be sent is defined by the key included in the data sent rather than by + `tile_id` as in cases below. + + :param api_version: version of API to be used + :param api_key: your API key + + **Example request**: + + .. sourcecode:: http + + POST /api/v0.1/my_key/push + Host: localhost:7272 + POST data: tile=text key=id_1 data={"text": "Hello world!"} + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: text/html; charset=UTF-8 + + Tile's data pushed successfully. + +.. http:post:: /api/(api_version)/(api_key)/tileconfig/(tile_id) + + Configures tile specified by `tile_id`. The configuration should comply with + the specification of a given tile type. + + :param api_version: version of API to be used + :param api_key: your API key + :param tile_id: unique tile's ID from your ``layout_config.yaml`` file + + **Example request**: + + .. sourcecode:: http + + GET /api/v0.1/my_key/tileconfig/id_1 + Host: localhost:7272 + POST data: value={"font_color": "#00FF00"} + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: text/html; charset=UTF-8 + + Tile's config updated. + + +.. http:delete:: /api/(api_version)/(api_key)/tileconfig/(tile_id) + + Resets configuration of the tile specified by `tile_id`. + + :param api_version: version of API to be used + :param api_key: your API key + :param tile_id: unique tile's ID from your ``layout_config.yaml`` file + + **Example request**: + + .. sourcecode:: http + + DELETE /api/v0.1/my_key/tileconfig/id_1 + Host: localhost:7272 + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: text/html; charset=UTF-8 + + Tile's config deleted. + +.. http:get:: /api/(api_version)/(api_key)/tiledata/(tile_id) + + Retrieves data belonging to the tile specified by `tile_id`. May be useful for diagnostics. + + :param api_version: version of API to be used + :param api_key: your API key + :param tile_id: unique tile's ID from your ``layout_config.yaml`` file + + **Example request**: + + .. sourcecode:: http + + GET /api/v0.1/my_key/tiledata/id_1 + Host: localhost:7272 + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json; charset=UTF-8 + + { + "tile_template": "text", + "meta": { + "font_color": "#ff9618", + "font_size": "45px" + }, + "data": { + "text": "Lorem ipsum." + }, + "id": "id_1" + } + +.. http:delete:: /api/(api_version)/(api_key)/tiledata/(tile_id) + + Removes everything belonging to the tile given by `tile_id` from Redis. + + :param api_version: version of API to be used + :param api_key: your API key + :param tile_id: unique tile's ID from your ``layout_config.yaml`` file + + **Example request**: + + .. sourcecode:: http + + DELETE /api/v0.1/my_key/tiledata/id_1 + Host: localhost:7272 + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: text/html; charset=UTF-8 + + Tile's data deleted. + +.. http:get:: /api/(api_version)/(api_key)/info + + Provides information on project and user configuration. This resource has + been created for debugging purposes. + + :param api_version: version of API to be used + :param api_key: your API key + + **Example request**: + + .. sourcecode:: http + + GET /api/v0.1/my_key/info + Host: localhost:7272 + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json; charset=UTF-8 + + { + "tipboard_version": "1.3.0", + "project_layout_config": "/home/pylabs/.tipboard/layout_config.yaml", + "redis_db": { + "host": "localhost", + "db": 4, + "port": 6379 + }, + "project_name": "pylabs" + } diff --git a/doc/changelog.rst b/doc/changelog.rst new file mode 100644 index 0000000..d9e113e --- /dev/null +++ b/doc/changelog.rst @@ -0,0 +1 @@ +.. include:: ../CHANGES.rst diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..7fe4c27 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,265 @@ +# -*- coding: utf-8 -*- +# +# Tipboard documentation build configuration file, created by +# sphinx-quickstart on Mon Mar 17 10:55:17 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# 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. +#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.todo', + 'sphinxcontrib.httpdomain', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Tipboard' +copyright = u'2013-2014, Allegro Group' + +# 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 = '1.4.0' +# The full version, including alpha/beta/rc tags. +release = '1.4.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- 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 = 'default' + +# 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 themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# 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'] + +# 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 '', 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. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_domain_indices = False + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Tipboarddoc' + + +# -- 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': '', +} + +# 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 = [ + ('index', 'Tipboard.tex', u'Tipboard Documentation', + u'Allegro Group', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'tipboard', u'Tipboard Documentation', + [u'Allegro Group'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- 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 = [ + ('index', 'Tipboard', u'Tipboard Documentation', + u'Allegro Group', 'Tipboard', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Misc options --------------------------------------------------------- +todo_include_todos = True diff --git a/doc/configuration.rst b/doc/configuration.rst new file mode 100644 index 0000000..a4d8f0b --- /dev/null +++ b/doc/configuration.rst @@ -0,0 +1,241 @@ +============= +Configuration +============= + +The description below assumes that you have installed Tipboard correctly and +use a default configuration that is the starting point for steps presented +below (see section :ref:`installation`). + +Default configuration +--------------------- + +Tipboard launched after installation present a basic, empty layout – empty +tiles in 2 lines with 4 columns each. If you want to modify them, create a +"clean" config, where your changes will be introduced. Use the command:: + + (tb-env)$ tipboard create_project <name_of_project> + +It will create the ``~/.tipboard`` dir with the following content: + +* ``settings-local.yaml`` file that defines the layout of tiles on the + dashboard you are creating; + +* ``settings-local.py`` file in which you can overwrite default (global) + application settings; a description of options and their default values has + been presented in `this file + <https://github.com/allegro/tipboard/blob/develop/tipboard/settings.py>`_; + +* ``custom_tiles`` subdir to place your own tiles. + +.. note:: + + Before you send anything to your tiles, you have to get your API key + first, which is described in the :ref:`api_key` section. + +Launching Tipboard app +---------------------- + +After you have logged in to your machine, you may launch Tipboard with the +command:: + + (tb-env)$ tipboard runserver [<host>] [<port>] + +...where ``host`` and ``port`` parameters are optional (by default these are +``localhost`` and ``7272``; if you want the application to listen on all the +network interfaces, set ``host`` to ``0.0.0.0``). + +Customising tile layout +----------------------- + +As mentioned previously, the layout of tiles in a dashboard is defined by +``layout_config.yaml`` file. The file is in the `YAML <http://yaml.org>`_ +format, the description of which is beyond the scope of this manual. However, +it is worth indicating that YAML has certain format requirements – +**indentation should have a unified structure** (be a multiplication of a +number, e.g. 4), when creating indentations **spaces should not be mixed with +tabs**. + +Below you can find a list of options that can be saved in the file. +Indentations indicate the position of a given option in the configuration (e.g. +``details`` are superior to ``page_title``). + +:: + + details + page_tile + layout + row_X_of_Y + col_X_of_Y + tile_template + tile_id + tile + timeout + +where: + +.. describe:: details + + A section that contains additional configuration parameters; for the time + being it is only ‘page_title’; depending on his needs, the users add other + elements. + +.. describe:: page_tile + + A section that defines the title of a page to appear in the web browser + after entering the dashboard. + +.. describe:: layout + + A section that contains a proper configuration of the tile layout. + +.. describe:: row_X_of_Y + + Defines a row hight; a sum of Xs should equal Y. + +.. describe:: col_X_of_Y + + Similar to above but concerns a column width in a given row. + +.. describe:: tile_template + + The name of a tile template to be displayed (e.g. ``pie_chart``, + ``line_chart``, ``cumulative_flow``) + +.. describe:: tile_id + + A tile identifier in a HTML document and key identifier in Redis. + +.. describe:: title + + A title to be displayed in the upper part of the tile. + +.. describe:: timeout + + The length (in seconds) of data life (if data is not sent during this time, + you will be informed that the data is stalled). Since interval used by the + application to check for those timeouts is 5 seconds, it doesn't make sense + to set this value smaller than this. + + .. versionadded:: 1.3.0 + +The method of using ``row_X_of_Y`` and ``col_X_of_Y`` has been presented in the +examples below. If you want to see how it's done "from the kitchen", and you +have some basic knowledge of CSS styling, have a look `here +<https://github.com/allegro/tipboard/blob/develop/tipboard/static/css/layout.css>`_; + +.. note:: + + If you want to present a lot of data on your dashboard, consider dividing + all your tiles into two (or more) separate dashboards. Tiles offer a limited + capacity and if you "feed" them with too much data (e.g. long lines of + text), it is possible the dashboard will get broken. + +Setting tiles' rotation +~~~~~~~~~~~~~~~~~~~~~~~ + +One of the most useful functions is defining tiles to rotate. In a single +container (i.e. in one of the fields indicated by ``col_X_of_Y`` and +``row_X_of_Y``), you may define a few tiles to be displayed in this location as +items rotating at intervals defined in the configuration (similar to ads +rotating on bus/tram stops, so-called *citylights*). To achieve that: + +* add the ``flip-time-xx`` class to a container, where ``xx`` is rotation + interval in seconds; +* add tile to the container. + +The example below presents a container with two tiles (one of the ``empty`` type, +the other of the ``text`` type) to rotate every 2 seconds (``flip-time-2``). +The rotation will start with the ``empty`` type tile:: + + layout: + - row_1_of_2: + - col_1_of_4 flip-time-2: + - tile_template: empty + tile_id: empty + title: Empty Tile 2 + + - tile_template: text + tile_id: text + title: Empty Tile + +Sample layout +~~~~~~~~~~~~~ + +Let's assume we want to define a layout as on the scheme below (i.e. a division +into 2 equal rows, with the upper one divided into 4 columns, and the lower one +divided into 3 columns):: + + +-------+--------+--------+-------+ + | | | | | + | | | | | + | | | | | + | | | | | + +-------+--+-----+----+---+-------+ + | | | | + | | | | + | | | | + | | | | + +----------+----------+-----------+ + +...its corresponding configuration file should look as follows (for brevity, I +will present only the ``layout`` section, skipping the ``tile_template``, +``title_id``, etc.):: + + layout: + row_1_of_2: + col_1_of_4: + col_1_of_4: + col_1_of_4: + col_1_of_4: + row_1_of_2: + col_1_of_3: + col_1_of_3: + col_1_of_3: + +Multiple dashboards per application's instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. versionadded:: 1.3.0 + +It is possible to define multiple dashboards per application's instance. In +order to achieve that, you just create separate layout config files (one per +every dashboard) - having done that, your dashboards will be available at:: + + http://localhost:7272/<name_of_layout_config_file> + +For example, having two layout config files ``my_first_dashboard.yaml`` and +``my_second_dashboard.yaml``, the corresponding dashboards can be accessed +via:: + + http://localhost:7272/my_first_dashboard + http://localhost:7272/my_second_dashboard + +.. note:: + + You have to strip the ``.yaml`` file extension when constructing your URLs. + +When it comes to feeding those dashboards with data, the future data location +is specified by tile IDs (unique within application instance). Therefore, there +is no need to specify different URLs for different dashboards - having tiles' +IDs, Tipboard will make sure that your data is delivered where it should be. + +Multiple rotating dashboards +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.3.0 + +If you have defined several dashboards (as described above), you may want to +rotate (flip) them periodically. If you are unsure what that means, think of +extensions like Revolver (Chrome) or Tab Slideshow (Firefox). + +To achieve that, you need: + +* at least two dashboards (well, that's kind of obvious) +* in the file ``settings-local.py`` add the variable ``FLIPBOARD_INTERVAL = + <seconds>`` (e.g. ``FLIPBOARD_INTERVAL = 5``) + +The above solution will make all your dashboards rotate - if you want to limit +this behavior and rotate only certain dashboards, just add another parameter +``FLIPBOARD_SEQUENCE`` which is just a list of dashboard names that should be +taken into account, e.g.:: + + FLIPBOARD_SEQUENCE = ['my_first_dashboard', 'my_third_dashboard'] diff --git a/doc/extras.rst b/doc/extras.rst new file mode 100644 index 0000000..396fb35 --- /dev/null +++ b/doc/extras.rst @@ -0,0 +1,58 @@ +====== +Extras +====== + +Here you will find description of components which are not a part of the +Tipboard project *per se*, although they may be useful to some of its users. +Assuming standard installation, you can find them here:: + + <path_to_your_virtualenv>/lib/python2.7/site-packages/tipboard/extras + +.. note:: + + If you have developed something of similar nature and you are willing to + share it, we encourage you to make a pull request to our repo. Thanks! + +``jira-ds.py`` +-------------- + +Script for fetching frequently used data from `JIRA +<https://www.atlassian.com/software/jira>`_ issue tracker, in order to present +it on your dashboards. Returns requested data to stdout in JSON format. For +the list of available options see ``jira-ds.py --help``. + +This script is basically a wrapper around ``jira-ds.js``, so those two files +shouldn't be separated. Requires `CasperJS <http://casperjs.org/>`_ and +`PhantomJS <http://phantomjs.org/>`_ installed somewhere in your path (we +suggest using `npm <http://nodejs.org/>`_ for that). + +Before you start using them, remember to fill in ``JIRA_CREDENTIALS`` and +``JIRA_BASE_URL`` (in ``jira-ds.py``) as well as ``url_jira`` and +``url_jira_login`` (in ``jira-ds.js``) with the your JIRA credentials, location +of your JIRA instance and its login page. + +Tested with JIRA 6.1.x. + + +``client_code_example.py`` +-------------------------- + +Simple Python script targeted to novice users serving as an example how to glue +together three steps: fetching data, processing it and then sending it to the +tile. See comments in the source code for further explaination. + + +``fabfile.py`` +-------------- + +Script for quick, automated installations on remote machines. + +You need to have `fabric <https://github.com/ronnix/fabtools>`_ and +`fabtools <http://fabtools.readthedocs.org>`_ to use remote install script. + +Run:: + + fab -H root@host install + +-- it will install all needed ``.deb`` packages, create virualenv and set up +Tipboard service using master branch from our main repo. diff --git a/doc/img/advanced-plot.png b/doc/img/advanced-plot.png Binary files differnew file mode 100644 index 0000000..94da500 --- /dev/null +++ b/doc/img/advanced-plot.png diff --git a/doc/img/bar-chart.png b/doc/img/bar-chart.png Binary files differnew file mode 100644 index 0000000..7cf3048 --- /dev/null +++ b/doc/img/bar-chart.png diff --git a/doc/img/big-value.png b/doc/img/big-value.png Binary files differnew file mode 100644 index 0000000..b59bb52 --- /dev/null +++ b/doc/img/big-value.png diff --git a/doc/img/cumulative-flow.png b/doc/img/cumulative-flow.png Binary files differnew file mode 100644 index 0000000..13c9aaa --- /dev/null +++ b/doc/img/cumulative-flow.png diff --git a/doc/img/fancy-listing.png b/doc/img/fancy-listing.png Binary files differnew file mode 100644 index 0000000..e5ab907 --- /dev/null +++ b/doc/img/fancy-listing.png diff --git a/doc/img/just-value.png b/doc/img/just-value.png Binary files differnew file mode 100644 index 0000000..43458d4 --- /dev/null +++ b/doc/img/just-value.png diff --git a/doc/img/line-chart.png b/doc/img/line-chart.png Binary files differnew file mode 100644 index 0000000..9bf030d --- /dev/null +++ b/doc/img/line-chart.png diff --git a/doc/img/listing.png b/doc/img/listing.png Binary files differnew file mode 100644 index 0000000..0bedee5 --- /dev/null +++ b/doc/img/listing.png diff --git a/doc/img/norm-chart.png b/doc/img/norm-chart.png Binary files differnew file mode 100644 index 0000000..15bf7bd --- /dev/null +++ b/doc/img/norm-chart.png diff --git a/doc/img/pie-chart.png b/doc/img/pie-chart.png Binary files differnew file mode 100644 index 0000000..20521fa --- /dev/null +++ b/doc/img/pie-chart.png diff --git a/doc/img/simple-percentage.png b/doc/img/simple-percentage.png Binary files differnew file mode 100644 index 0000000..2a86b31 --- /dev/null +++ b/doc/img/simple-percentage.png diff --git a/doc/img/smaller/advanced-plot.png b/doc/img/smaller/advanced-plot.png Binary files differnew file mode 100644 index 0000000..d11f307 --- /dev/null +++ b/doc/img/smaller/advanced-plot.png diff --git a/doc/img/smaller/bar-chart.png b/doc/img/smaller/bar-chart.png Binary files differnew file mode 100644 index 0000000..34241f6 --- /dev/null +++ b/doc/img/smaller/bar-chart.png diff --git a/doc/img/smaller/big-value.png b/doc/img/smaller/big-value.png Binary files differnew file mode 100644 index 0000000..7516c43 --- /dev/null +++ b/doc/img/smaller/big-value.png diff --git a/doc/img/smaller/cumulative-flow.png b/doc/img/smaller/cumulative-flow.png Binary files differnew file mode 100644 index 0000000..c0cfd5a --- /dev/null +++ b/doc/img/smaller/cumulative-flow.png diff --git a/doc/img/smaller/fancy-listing.png b/doc/img/smaller/fancy-listing.png Binary files differnew file mode 100644 index 0000000..b241ac6 --- /dev/null +++ b/doc/img/smaller/fancy-listing.png diff --git a/doc/img/smaller/just-value.png b/doc/img/smaller/just-value.png Binary files differnew file mode 100644 index 0000000..d3c8cf0 --- /dev/null +++ b/doc/img/smaller/just-value.png diff --git a/doc/img/smaller/line-chart.png b/doc/img/smaller/line-chart.png Binary files differnew file mode 100644 index 0000000..2873303 --- /dev/null +++ b/doc/img/smaller/line-chart.png diff --git a/doc/img/smaller/listing.png b/doc/img/smaller/listing.png Binary files differnew file mode 100644 index 0000000..0b11eb9 --- /dev/null +++ b/doc/img/smaller/listing.png diff --git a/doc/img/smaller/norm-chart.png b/doc/img/smaller/norm-chart.png Binary files differnew file mode 100644 index 0000000..739ffcd --- /dev/null +++ b/doc/img/smaller/norm-chart.png diff --git a/doc/img/smaller/pie-chart.png b/doc/img/smaller/pie-chart.png Binary files differnew file mode 100644 index 0000000..d312bdf --- /dev/null +++ b/doc/img/smaller/pie-chart.png diff --git a/doc/img/smaller/simple-percentage.png b/doc/img/smaller/simple-percentage.png Binary files differnew file mode 100644 index 0000000..790b77a --- /dev/null +++ b/doc/img/smaller/simple-percentage.png diff --git a/doc/img/smaller/text.png b/doc/img/smaller/text.png Binary files differnew file mode 100644 index 0000000..6819889 --- /dev/null +++ b/doc/img/smaller/text.png diff --git a/doc/img/text.png b/doc/img/text.png Binary files differnew file mode 100644 index 0000000..b47e9c6 --- /dev/null +++ b/doc/img/text.png diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..15ebda9 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,16 @@ +Welcome to Tipboard's documentation! +==================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + overview + installation + configuration + tiles + api + extras + changelog + license diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 0000000..9f16ff0 --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,98 @@ +.. _installation: + +============== +How to install +============== + +You can install Tipboard on a variety of sensible operating systems. This guide +assumes **Ubuntu Server 12.04 LTS** and presents shell command examples +accordingly. + +Prerequisites +------------- + +Tipboard requires Python 2.7 which can be installed with this command:: + + $ sudo apt-get install python-dev python-virtualenv + +Another dependency which needs to be satisfied before proceeding further is +`Redis <http://redis.io/>`_ server:: + + $ sudo apt-get install redis-server + +Optional yet recommended packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One of such packages is ``supervisor`` - it facilitates program administration +(e.g. its reboot), especially if there are a few instances launched on the +machine. + +Based on the Tornado framework, Tipboard has a built-in server available, but +a typical use case assumes communication with the world via reverse proxy (e.g. +using ``nginx`` or ``apache``). + +.. note:: + + Although configuration of reverse proxy is out of scope of this manual, we + would like to emphasise that Tipboard use Web Sockets – a relatively new + mechanism – and thus you should ensure a server in a version that will + support it (e.g. ``nginx`` >= 1.3.13 or ``apache2`` >= 2.4.6). By default + Ubuntu 12.04 offers older versions – you may then use backports. + +.. note:: + + It will be useful to have an updated version of ``pip`` (i.e. >= 1.4) and + ``virtualenv`` (i.e. >= 1.10). + +Preparing environment for installation +-------------------------------------- + +Start by creating a user, the privileges of whom will be used by the +application (for the needs of this manual, let's create the user "pylabs"):: + + $ sudo adduser pylabs --home /home/pylabs --shell /bin/bash + $ sudo su - pylabs + +Virtual environment +~~~~~~~~~~~~~~~~~~~ + +Continue by creating a virtual environment that will help you conveniently +separate your instance from what you already have installed in the system +(let's say we name it "tb-env"):: + + $ cd /home/pylabs + $ virtualenv tb-env + +Activate the created virtual environment with the following command:: + + $ source /home/pylabs/tb-env/bin/activate + +.. note:: + + It is worth saving the above line in the ``~/.profile`` file. As a result, + the virtual environment will be activated automatically whenever you log in + on the machine. + +.. note:: + + Further setup assumes an activated virtual environment, which is denoted by + ``(tb-env)`` prefix in your shell prompt. + +Installing with pip +------------------- + +After creating and activating virtualenv, install the latest (current) version +of Tipboard package available on pypi ("Python Package Index") with the +following command:: + + (tb-env)$ pip install tipboard + +Verification +------------ + +To verify if installation has been successful, launch this command:: + + (tb-env)$ tipboard runserver + +If you see the message "Listening on port..." instead of errors, it means that +installation was successful and you may proceed to the next section. diff --git a/doc/license.rst b/doc/license.rst new file mode 100644 index 0000000..d8e3824 --- /dev/null +++ b/doc/license.rst @@ -0,0 +1,5 @@ +License +_______ + +.. include:: ../LICENSE.rst + :literal: diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 0000000..dc3f75f --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,21 @@ +Overview +-------- + +Tipboard is a system for creating dashboards, written in JavaScript and Python. +Its widgets ('tiles' in Tipboard's terminology) are completely separated from +data sources, which provides great flexibility and relatively high degree of +possible customizations. + +Because of its intended target (displaying various data and statistics in your +office), it is optimized for larger screens. + +Similar projects: `Geckoboard <http://www.geckoboard.com/>`_, +`Dashing <http://shopify.github.io/dashing/>`_. + +Project assumptions +~~~~~~~~~~~~~~~~~~~ + +#. Defining a dashboard layout (number of lines, columns, types of tiles etc.). +#. Clear separation between tiles and data sources. +#. Ability to create own tiles and scripts querying data sources (e.g. Jira, Bamboo, Confluence etc.). +#. Feeding tiles via REST API. diff --git a/doc/tile__advanced_plot.rst b/doc/tile__advanced_plot.rst new file mode 100644 index 0000000..afeabab --- /dev/null +++ b/doc/tile__advanced_plot.rst @@ -0,0 +1,140 @@ +================= +``advanced_plot`` +================= + +.. image:: img/smaller/advanced-plot.png + +**Description** + +This tile is for more demanding users. It basically allows to display arbitrary +type of chart/plot from the `jqPlot <http://www.jqplot.com/>`_ library, along +with the title and description (both are optional). + +Before you start experimenting with jqPlot library, we suggest to familiarize +yourself with `this manual +<http://www.jqplot.com/docs/files/usage-txt.html#jqPlot_Usage>`_. After that +you should check out `options tutorial +<http://www.jqplot.com/docs/files/optionsTutorial-txt.html#Options_Tutorial>`_ +and `options summary <http://www.jqplot.com/docs/files/jqplot-core-js.html>`_. + +Here you will find `some examples <http://www.jqplot.com/deploy/dist/examples/>`_. + +**Content** + +:: + + "data" = { + "title": "<tile>", + "description": "<description>", + "plot_data": "<data>" + } + +where: + +.. describe:: title, description + + Title and description (subtitle) for the tile. + +.. describe:: plot_data + + Data that will be fed directly to your plot. Its form depends on the + specific type of plot that you are going to use - see jqPlot's documentation + for the details. + +Example (using horizontal `Bar Chart +<http://www.jqplot.com/deploy/dist/examples/barTest.html>`_ - third example +from the top):: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=advanced_plot" + -d "key=<tile_id>" + -d 'data={"title": "Metric Tons per Year", "description": "", + "plot_data": [[[2,1], [4,2], [6,3], [3,4]], + [[5,1], [1,2], [3,3], [4,4]], + [[4,1], [7,2], [1,3], [2,4]]]}' + +.. note:: + + Keep in mind that ``advanced_plot`` can display arbitrary charts from jqPlot + library, and more than often they are quite different when it comes to the + parameters required etc. + +**Configuration** + +:: + + value = { + "value": "<jqplot_config>" + } + +where: + +.. describe:: value + + Raw configuration that will be passed directly to jqPlot and which should + obey the rules defined by the jqPlot library. Internally, this config will + be passed as ``$.jqplot(some-container, some-data, our-config)``. + + If such configuration contains one of jqPlot's renderers, its name should be + passed as a string, according to the table below: + + +--------------------------------------+-------------------------------+ + | jqPlot's renderer | string to send | + +======================================+===============================+ + | ``$.jqplot.BarRenderer`` | ``"BarRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.BlockRenderer`` | ``"BlockRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.BubbleRenderer`` | ``"BubbleRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.CanvasAxisLabelRenderer`` | ``"CanvasAxisLabelRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.CanvasAxisTickRenderer`` | ``"CanvasAxisTickRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.CanvasTextRenderer`` | ``"CanvasTextRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.CategoryAxisRenderer`` | ``"CategoryAxisRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.DateAxisRenderer`` | ``"DateAxisRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.DonutRenderer`` | ``"DonutRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.EnhancedLegendRenderer`` | ``"EnhancedLegendRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.FunnelRenderer`` | ``"FunnelRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.LogAxisRenderer`` | ``"LogAxisRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.MekkoAxisRenderer`` | ``"MekkoAxisRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.MekkoRenderer`` | ``"MekkoRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.MeterGaugeRenderer`` | ``"MeterGaugeRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.OhlcRenderer`` | ``"OhlcRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.PieRenderer`` | ``"PieRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.PyramidAxisRenderer`` | ``"PyramidAxisRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.PyramidGridRenderer`` | ``"PyramidGridRenderer"`` | + +--------------------------------------+-------------------------------+ + | ``$.jqplot.PyramidRenderer`` | ``"PyramidRenderer"`` | + +--------------------------------------+-------------------------------+ + +Example (using horizontal `Bar Chart +<http://www.jqplot.com/deploy/dist/examples/barTest.html>`_ - third example +from the top):: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id> + -X POST + -d 'value={ + "seriesDefaults": { + "trendline": {"show": false}, + "renderer":"BarRenderer", + "pointLabels": {"show": true, "location": "e", "edgeTolerance": -15}, + "shadowAngle": 135, + "rendererOptions": {"barDirection": "horizontal"} + }, + "axes": {"yaxis": { "renderer": "CategoryAxisRenderer"}}}' diff --git a/doc/tile__bar_chart.rst b/doc/tile__bar_chart.rst new file mode 100644 index 0000000..47dfd32 --- /dev/null +++ b/doc/tile__bar_chart.rst @@ -0,0 +1,61 @@ +============= +``bar_chart`` +============= + +.. image:: img/smaller/bar-chart.png + +**Description** + +Tile displaying data in the form of horizontal bar charts. Each cart may +consist of one or more series of data - in the latter case, such bars are +grouped respectively. There are no "hard" limits when it comes to the number of +charts/series, although we suggest to keep them down to 3 charts of 2 series +each. + +**Content** + +:: + + data = { + "title": "<title>", + "subtitle": "<subtitle>", + "ticks": ["<label1>", "<label2>", "<label3>" ...], + "series_list": [[<val1>, <val2>, <val3>, ...], + [<val1>, <val2>, <val3>, ...]] + } + +where: + +.. describe:: title, subtitle + + Title and subtitle displayed on the top of the tile. + +.. describe:: ticks + + Labels to be displayed on the left side of the charts. + +.. describe:: series_list + + List of series, as name suggests. ``[[1, 2]]`` will give one chart of two + bars, ``[[3, 4, 5], [6, 7, 8]]`` will give two charts of three bars each. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=bar_chart" + -d "key=<tile_id>" + -d 'data={"title": "The A-Team", + "subtitle": "Velocity (Last tree sprints)", + "ticks": ["n-2", "n-1", "Last (n)"], + "series_list": [[49, 50, 35], [13, 45, 9]]}' + +**Configuration** + +This tile does not offer any configuration options. + +.. note:: + + In case of displaying more than one charts on the same tile, the number of + values in ``series_list`` for every chart should be the same (and they + should be equal to the number of ``ticks``. diff --git a/doc/tile__big_value.rst b/doc/tile__big_value.rst new file mode 100644 index 0000000..dbdcad2 --- /dev/null +++ b/doc/tile__big_value.rst @@ -0,0 +1,97 @@ +============= +``big_value`` +============= + +.. image:: img/smaller/big-value.png + +**Description** + +This is a variation of ``simple_percentage`` tile. It has slightly different +footer (four possible values instead of just two; values are displayed on the +right side of the label instead of below), and the main value (``big_value``) +is little bit bigger. + +**Content** + +:: + + data = { + "title": "<title>", + "description": "<description>", + "big-value": "<value>", + "upper-left-label": "<label>", + "upper-left-value": "<value>", + "lower-left-label": "<label>", + "lower-left-value": "<value>", + "upper-right-label": "<label>", + "upper-right-value": "<value>", + "lower-right-label": "<label>", + "lower-right-value": "<value>" + } + +where: + +.. describe:: title, description + + Title and description (subtitle) for the tile. + +.. describe:: big_value + + Main value, which treated as a string, so it can contain symbols like ``%`` etc. + +.. describe:: upper-left-value, lower-left-value, upper-right-value, lower-right-value + + Smaller, bottom-left and bottom-right values. + +.. describe:: upper-left-label, lower-left-label, upper-right-label, lower-right-label + + Labels for above values. + + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=big_value" + -d "key=<tile_id>" + -d 'data={"title": "Tickets", + "description": "number of blockers", + "big-value": "314", + "upper-left-label": "critical:", + "upper-left-value": "1020", + "lower-left-label": "major:", + "lower-left-value": "8609", + "upper-right-label": "minor:", + "upper-right-value": "7532", + "lower-right-label": "all:", + "lower-right-value": "19 853"}' + +**Configuration** + +:: + + value = { + "big_value_color": "<color>", + "fading_background": <BOOLEAN> + } + +where: + +.. describe:: big_value_color + + Background color for ``big_value`` in a hexadecimal form or color name (e.g. + ``#94C140`` or ``green``). + +.. describe:: fading_background + + Turns on/off background pulsation for ``big_value`` (may be useful for + alerts etc.). + + .. versionadded:: 1.3.0 + + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id> + -X POST + -d 'value={"big_value_color": "green", "fading_background": true}' diff --git a/doc/tile__cumulative_flow.rst b/doc/tile__cumulative_flow.rst new file mode 100644 index 0000000..c26d46a --- /dev/null +++ b/doc/tile__cumulative_flow.rst @@ -0,0 +1,68 @@ +=================== +``cumulative_flow`` +=================== + +.. image:: img/smaller/cumulative-flow.png + +**Description** + +Cumulative chart using `jqPlot <http://www.jqplot.com/>`_ library. Allows to +display up to seven plots on a single chart. + +**Content** + +:: + + data = { + "title": "<title>", + "series_list": [{"label": "<label1>", "series": [<val1>, <val2>, ...]}, + {"label": "<label2>", "series": [<val1>, <val2>, ...]}] + } + +where: + +.. describe:: title + + Title to be displayed above the labels. + +.. describe:: series_list + + A container (i.e. list of objects) for the data; each such object + corresponding to a single plot consists of two keys: ``label`` and + ``series``, where the latter is a list of values constructing the plot. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=cumulative_flow" + -d "key=<tile_id>" + -d 'data={"title": "My title:", + "series_list": [{"label": "label 1", "series": [ 0, 0, 0, 0, 1, 1, 2, 2, 1, 1, 1, 0, 0, 2, 0 ]}, + {"label": "label 2", "series": [ 0, 5, 0, 0, 1, 0, 0, 3, 0, 0, 0, 7, 8, 9, 1 ]}]}' + +**Configuration** + +:: + + value = {"ticks": [[<key>, "<value>"], [<key>, "<value>"], ... ]} + +where: + +.. describe:: ticks + + List of elements defining x-axis; each such element is a list of form ``[k, + v]`` where ``k`` is an oridinal number designating position of such tick and + ``v`` is a string which will be displayed in that place. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id> + -X POST + -d 'value={"ticks": [[1, "mon"], [2, "tue"], [3, "wed"], [4, "thu"], [5, "fri"], [6, "sat"], [7, "sun"]]}' + +.. note:: + + If ``series_list`` contains more than one object (which is the case 99% of + the time), each one of them should have ``series`` list of the same length - + and this lenght should be equal to the number of ``ticks``. diff --git a/doc/tile__fancy_listing.rst b/doc/tile__fancy_listing.rst new file mode 100644 index 0000000..902bdc9 --- /dev/null +++ b/doc/tile__fancy_listing.rst @@ -0,0 +1,91 @@ +================= +``fancy_listing`` +================= + +.. image:: img/smaller/fancy-listing.png + +**Description** + +This tile is a more sophisticated version of ``listing`` tile offering colored +labels and centering options. Each entry is an object containing three keys: +``label``, ``text`` and ``description``. Threrefore, ``data`` (i.e. content) is +just a list of such objects. + +**Content** + +:: + + "data" = [ + {"label": "<label1>", "text": "<entry1>", "description": "<desc1>" }, + {"label": "<label2>", "text": "<entry2>", "description": "<desc2>" } + ] + +where: + +.. describe:: label + + Smaller label displayed on the left which can be colored. + +.. describe:: text + + A textual entry to be displayed next to the label. + +.. describe:: description + + Subtitle displayed below ``text`` element. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=fancy_listing" + -d "key=<tile_id>" + -d 'data=[{"label": "My label 1", "text": "Lorem ipsum", "description": "such description" }, + {"label": "My label 2", "text": "Dolor sit", "description": "yet another" }, + {"label": "My label 3", "text": "Amet", "description": "" }]' + +**Configuration** + +:: + + value = { + "vertical_center": <BOOLEAN>, + "<position>": { + "label_color": "<color>", + "center": <BOOLEAN> + }, + } + +where: + +.. describe:: vertical_center + + Centers vertically all the entries (along with their labels). + + .. versionadded:: 1.3.0 + +.. describe:: position + + Tells which entry (starting from 1) should be a subject to ``label_color`` + and ``center`` (specified as subkeys of ``position``). + + .. describe:: label_color + + Sets the color of label for the entry given with ``position``. Color can + be specified in a hexadecimal form (``#RRGGBB``) or by name (e.g. + ``green``). + + .. describe:: center + + Centers horizontally entry's ``text`` and ``description`` (it does not + affect label's position). + + .. versionadded:: 1.3.0 + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id> + -X POST + -d 'value={"vertical_center": true, + "1": {"label_color": "red", "center": true}, + "3": {"label_color": "green", "center": true }}' diff --git a/doc/tile__just_value.rst b/doc/tile__just_value.rst new file mode 100644 index 0000000..0d76082 --- /dev/null +++ b/doc/tile__just_value.rst @@ -0,0 +1,67 @@ +============== +``just_value`` +============== + +.. image:: img/smaller/just-value.png + +**Description** + +Tile for displaying single, short information with a possibility to change its +background color. + +**Content** + +:: + + "data" = { + "title": "<title>", + "description": "<description>", + "just-value": "<value>" + } + +where: + +.. describe:: title, description + + Title and description (subtitle) for the tile. + +.. describe:: just-value + + Value to be displayed on the tile, with optionally colored background. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=just_value" + -d "key=<tile_id>" + -d 'data={"title": "Next release:", "description": "(days remaining)", "just-value": "23"}' + +**Configuration** + +:: + + value = { + "just-value-color": "<color>", + "fading_background": <BOOLEAN> + } + +where: + +.. describe:: just-value-color + + Background color for ``just-value`` in a hexadecimal form or color name (e.g. + ``#94C140`` or ``green``). + +.. describe:: fading_background + + Turns on/off background pulsation for ``just-value`` (may be useful for + alerts etc.). + + .. versionadded:: 1.3.0 + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id> + -X POST + -d 'value={"just-value-color": "green", "fading_background": true}' diff --git a/doc/tile__line_chart.rst b/doc/tile__line_chart.rst new file mode 100644 index 0000000..a7435b1 --- /dev/null +++ b/doc/tile__line_chart.rst @@ -0,0 +1,81 @@ +============== +``line_chart`` +============== + +.. image:: img/smaller/line-chart.png + +**Description** + +Line-chart using `jqPlot <http://www.jqplot.com/>`_ library. Allows to display +arbitrary number of plots on single chart, with automatical generation of trend +lines for them (which is turned on by default). + +**Content** + +:: + + data = { + "subtitle": "<subtitle_text">, + "description": "<description_text>", + "series_list": [[<series1>], [<series2>], [<series3>], ...] + } + +where: + +.. describe:: subtitle, description + + Additional text fields for charts descriptions (optional - you can pass + empty strings here). + +.. describe:: series_list + + Data for line-charts in a form of list of series, where each series + designates single chart; each element of a given series is a pair + ``[x_axis_value, y_axis_value]``. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=line_chart" + -d "key=example_line" + -d 'data={"subtitle": "averages from last week", + "description": "Sales in our dept", + "series_list": [[["23.09", 8326], ["24.09", 260630], ["25.09", 240933], ["26.09", 229639], ["27.09", 190240], ["28.09", 125272], ["29.09", 3685]], + [["23.09", 3685], ["24.09", 125272], ["25.09", 190240], ["26.09", 229639], ["27.09", 240933], ["28.09", 260630], ["29.09", 108326]]]}' + +-- this will give two plots on a single chart (on x-axis there will be "23.09", +"24.09", "25.09" and so on) with heading "Sales in our dept" and subtitle +"averages from last week". + +**Configuration** + +:: + + value = {<jqplot_config>} + +where: + +.. describe:: jqplot_config + + Configuration params in the form described by `jqPlot documentation + <http://www.jqplot.com/tests/line-charts.php>`_. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/example_line + -X POST + -d 'value={"grid": {"drawGridLines": true, + "gridLineColor": "#FFFFFF", + "shadow": false, + "background": "#000000", + "borderWidth": 0}}' + +-- this will set up the grid (in white color), black background and will turn +off shadow effects as well as borders. + +.. note:: + + In case of displaying multiple plots on a single chart (e.g. for more than + one data series) you have to keep in mind that the ``x_axis_value`` values + should be the same for all of those plots. diff --git a/doc/tile__listing.rst b/doc/tile__listing.rst new file mode 100644 index 0000000..dbe2516 --- /dev/null +++ b/doc/tile__listing.rst @@ -0,0 +1,34 @@ +=========== +``listing`` +=========== + +.. image:: img/smaller/listing.png + +**Description** + +Very simple tile for displaying list of entries (up to seven) of arbitrary +content. For more sophisticated needs there is a ``fancy_listing`` tile. + +**Content** + +:: + + data = {"items": ["<entry1>", "<entry2>", ..., "<entry7>"]} + +where: + +.. describe:: items + + List of items (entries) to display. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=listing" + -d "key=<tile_id>" + -d "data={"items": ["Leader: 5", "Product Owner: 0", "Scrum Master: 3", "Developer: 0"]}" + +**Configuration** + +This tile does not offer any configuration options. diff --git a/doc/tile__norm_chart.rst b/doc/tile__norm_chart.rst new file mode 100644 index 0000000..6cfd8c0 --- /dev/null +++ b/doc/tile__norm_chart.rst @@ -0,0 +1,79 @@ +============== +``norm_chart`` +============== + +.. image:: img/smaller/norm-chart.png + +.. versionadded:: 1.3.0 + +**Description** + +"Curve vs norm" style chart. Suitable for situations, when you want to +compare some data with expected value ("norm") or put an emphasis on y-axis +values. + +**Content** + +:: + + "data" = { + "title": "<title>", + "description": "<description>", + "plot_data": [ [<series1>], [<series2>], [<series3>], ... ] + } + +where: + +.. describe:: title, description + + Title and description (subtitle) for the tile. + +.. describe:: plot_data + + Data for charts in a form of list of series, where each series designates + single chart; each element of a given series is a pair ``[x_axis_value, + y_axis_value]``. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=norm_chart" + -d "key=<tile_id>" + -d 'data={"title": "My title", + "description": "Some description", + "plot_data": [[[1, 2], [3, 5.12], [5, 13.1], [7, 33.6], [9, 85.9], [11, 219.9]], + [[6, 2], [3, 5.12], [5, 13.1], [7, 33.6], [9, 85.9], [11, 219.9]]]}' + +**Configuration** + +:: + + value = { + "easyNorms": [["<color>", <y-value>, <line_width>], ...] + } + +where: + +.. describe:: easyNorms + + List of norms to be displayed. Each norm consists of three elements: + + .. describe:: color + + Color which given norm should use - in a hexadecimal form or color name + (e.g. ``#94C140`` or ``green``). + + .. describe:: y-value + + Value for the norm. + + .. describe:: line_width + + Line thickness for the norm (in pixels). + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id> + -X POST + -d 'value={"easyNorms": [["yellow", 200, 2], ["green", 100, 2]]}' diff --git a/doc/tile__pie_chart.rst b/doc/tile__pie_chart.rst new file mode 100644 index 0000000..afd8f84 --- /dev/null +++ b/doc/tile__pie_chart.rst @@ -0,0 +1,64 @@ +============= +``pie_chart`` +============= + +.. image:: img/smaller/pie-chart.png + +**Description** + +"Pie-chart" style chart using `jqPlot <http://www.jqplot.com/>`_ library, with +optional legend. + +**Content** + +:: + + data = { + "title": "<optional_title>", + "pie_data": [[identifier1, value1], [identifier2, value2], ...] + } + +where: + +.. describe:: title + + Chart's title (optional). + +.. describe:: pie_data + + Data for pie-chart in a form of list of lists, where each sub-list is an + identifier-value pair. Percentage of the whole chart shared by given part is + calculated automatically by jqPlot - relatively to the sum of values of all + parts. + +Example:: + + curl http//localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=pie_chart" + -d "key=example_pie" + -d 'data={"title": "My title", "pie_data": [["Pie 1", 25], ["Pie 2", 25], ["Pie 3", 50]]}' + +-- this will result in a pie-chart with title "My title", divided by three +parts "Pie 1", "Pie 2" and "Pie 3". + +**Configuration** + +:: + + value = {<jqplot_config>} + +where: + +.. describe:: jqplot_config + + Configuration params in the form described by `jqPlot documentation + <http://www.jqplot.com/tests/pie-donut-charts.php>`_. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tild_id> + -X POST + -d 'value={"title": true, "legend": {"show": true, "location": "s"}}' + +-- this will result in a pie-chart with legend turned on at the bottom of the tile (``s`` stands for "south") - its title will be turned on as well. diff --git a/doc/tile__simple_percentage.rst b/doc/tile__simple_percentage.rst new file mode 100644 index 0000000..d0fbdc7 --- /dev/null +++ b/doc/tile__simple_percentage.rst @@ -0,0 +1,81 @@ +===================== +``simple_percentage`` +===================== + +.. image:: img/smaller/simple-percentage.png + +**Description** + +Tile displaying three arbitrary values (with labels) - one bigger ("main" +value) and two smaller (at the bottom-left and bottom-right of the tile). It is +possible to change background color for the main value. + +**Content** + +:: + + data = { + "title": "<title>", + "subtitle": "<subtitle>", + "big_value": "<value1>", + "left_value": "<value2>", + "right_value": "<value3>" + "left_label": "<label1>", + "right_label": "<label2>" + } + +where: + +.. describe:: title, subtitle + + They serve as a label for the ``big_value`` ("main" value). + +.. describe:: big_value + + Main value, which treated as a string, so it can contain symbols like ``%`` etc. + +.. describe:: left_value, right_value + + Smaller, bottom-left and bottom-right values. + +.. describe:: left_label, right_label + + Labels for above values. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=simple_percentage" + -d "key=<tile_id>" + -d 'data={"title": "My title", "subtitle": "My subtitle", "big_value": "100%", + "left_value": "50%", "left_label": "smaller label 1", + "right_value": "25%", "right_label": "smaller label 2"}' + +**Configuration** + +:: + + value = { + "big_value_color": "<color>", + "fading_background": <BOOLEAN> + } + +where: + +.. describe:: big_value_color + + Background color for ``big_value`` in a hexadecimal form or color name (e.g. + ``#94C140`` or ``green``). + +.. describe:: fading_background + + Turns on/off background pulsation for ``big_value`` (may be useful for alerts etc.). + + .. versionadded:: 1.3.0 + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/<tile_id> + -X POST + -d 'value={"big_value_color": "green", "fading_background": true}' diff --git a/doc/tile__text.rst b/doc/tile__text.rst new file mode 100644 index 0000000..e9318a7 --- /dev/null +++ b/doc/tile__text.rst @@ -0,0 +1,61 @@ +======== +``text`` +======== + +.. image:: img/smaller/text.png + +**Description** + +Simple text-tile designated to display... (surprise!) text. + +**Content** + +:: + + data = {"text": "<text_content>"} + +where: + +.. describe:: text_content + + A textual content to be displayed. + +Example:: + + curl http://localhot:7272/api/v0.1/<api_key>/push + -X POST + -d "tile=text" + -d "key=mytext" + -d 'data={"text": "Hello world!"}' + +**Configuration** + +:: + + value = {"<config_element>": "<config_value>"} + +where: + +.. describe:: config_element + + One of three attributes of displayed text (i.e. ``font_size``, ``color`` and + ``font_weight``). + +.. describe:: config_value + + Value matching above. + +Example:: + + curl http://localhost:7272/api/v0.1/<api_key>/tileconfig/mytext + -X POST + -d 'value={"font_color": "#00FF00"}' + +.. note:: + + Parameter ``font_size`` can be specified in two ways - as a number (e.g. + ``"font_size": 10``) or as a string (e.g. ``"font_size": "10px"``) - both of + them have the same effect. + + Keys ``font_size``, ``color``, ``font_weight`` with empty ``config_value`` + are ignored (in such case, they will inherit those values from parent CSS). diff --git a/doc/tiles.rst b/doc/tiles.rst new file mode 100644 index 0000000..0855a2f --- /dev/null +++ b/doc/tiles.rst @@ -0,0 +1,99 @@ +===== +Tiles +===== + +Every tile consists of an obligatory ``.html`` file and two optional ``.css`` +and ``.js`` files. All three files belonging to a tile should have the same +name that corresponds with the tile name – e.g. with the ``pie_chart`` tile +these are ``pie_chart.html``, ``pie_chart.css`` and ``pie_chart.js`` files +respectively. + +Customising tiles +----------------- + +If you want to modify a tile (e.g. change a CSS attribute, which obviously +cannot be done via API), copy a desired file in the folder of tiles delivered +with the application (i.e. +``<path_to_your_virtualenv>/lib/python2.7/site-packages/tipboard/tiles``), +paste it in your tile folder (i.e. ``~/.tipboard/custom_tiles``) and edit +according to your needs. + +Files in your ``custom_tiles`` folder take precedence over those shipped by +default with the application and thus you can easily replace desired elements +(e.g. if you want to change the text colour, just copy and edit the ``.css`` +file – without touching ``.html`` and ``.js`` files). We plan to introduce a +command simplifying this process in the future. + +Color palette +------------- + +Color palette used by Tipboard's tiles is defined as shown in the table below. +To retain consistency, we strongly suggest sticking to them while customising +tiles. + ++-------------+---------------------+ +| Value | Name | ++=============+=====================+ +| ``#000000`` | ``black`` | ++-------------+---------------------+ +| ``#FFFFFF`` | ``white`` | ++-------------+---------------------+ +| ``#25282D`` | ``tile_background`` | ++-------------+---------------------+ +| ``#DC5945`` | ``red`` | ++-------------+---------------------+ +| ``#FF9618`` | ``yellow`` | ++-------------+---------------------+ +| ``#94C140`` | ``green`` | ++-------------+---------------------+ +| ``#12B0C5`` | ``blue`` | ++-------------+---------------------+ +| ``#9C4274`` | ``violet`` | ++-------------+---------------------+ +| ``#EC663C`` | ``orange`` | ++-------------+---------------------+ +| ``#54C5C0`` | ``naval`` | ++-------------+---------------------+ + +Common elements +--------------- + +* tile's content (``data`` key) and its configuration (``value`` key) should be + send as two separate requests - once you have established desired + configuration it does not make much sense to send it over and over again; +* in order to reset tile's config, you just send an empty ``value`` key (e.g. + ``value = {}``). + +.. _tiles_library: + +Library of available tiles +-------------------------- + +In the following pages we present a "library" of available tiles (i.e. those +bundled with the application), which should serve as a specification how to +send data to them and how to set up its configuration options. + +.. toctree:: + :maxdepth: 2 + + tile__text + tile__pie_chart + tile__line_chart + tile__cumulative_flow + tile__simple_percentage + tile__listing + tile__bar_chart + tile__fancy_listing + tile__big_value + tile__just_value + tile__advanced_plot + tile__norm_chart + +.. note:: + + In order to keep brevity, all examples presented in specifications above do + not include any escape characters. Therefore, it's up to you to insert them + where necessary. + + And also, remember to set all the elements in angle brackets (e.g. + ``<api_key>``, ``<tile_id>`` etc.) to reflect your configuration. |
