Commit 1edf90b5 authored by Louis's avatar Louis
Browse files

[doc][DRAFT] More documentation draft

parent a9da4dff
Pipeline #7510 failed with stage
in 33 seconds
......@@ -19,7 +19,7 @@ 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('.'))
sys.path.insert(0, os.path.abspath('..'))
# -- General configuration ------------------------------------------------
......@@ -109,6 +109,8 @@ pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# Autodoc options
autodoc_member_order = 'bysource'
# -- Options for HTML output ----------------------------------------------
......
.. module:: pypimonitor.cell
Cell plugins
============
TODO
The content of cells is rendered by plugins. A :ref:`predefined list
<pluginlist>` is detailed below, but you can also :ref:`writeplugin`.
.. _pluginlist:
List of plugins
---------------
......@@ -124,23 +129,69 @@ Badge displaying Pypi version.
* ``slug``
Repository name, if different from the pypi package name.
.. _writeplugin:
Write your own
--------------
TODO
The HTML page is generated using the `Jinja2 <http://jinja.pocoo.org/>`_
template system, but you don't *have to* use it for your plugins.
A plugin is an object, subclass of :class:`Cell`. The
:meth:`Cell.render` method must be implemented: it is the
method that is called to fill a cell. Since for many usage, your plugin will
simply be a template, you can use the :class:`Jinja2` class,
which makes this a lot easier. Both classes makes it easy to define
:ref:`default and required arguments <defaultrequired>`, and to :ref:`log errors <errors>`.
Raw
^^^
TODO
.. autoclass:: Cell
:members: render, render_error, keyword, title, default, required
Jinja2
^^^^^^
TODO
.. autoclass:: Jinja2
:members: keyword, template
.. _defaultrequired:
Default and Required arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
A built-in features eases processing default and required arguments, for simple
cases. This is automatically done before calling the
:meth:`Cell.render` method.
If your plugin has absolute default values for some arguments, those can be set
in the :attr:`Cell.default` dictionary. Keys are arguments,
and values are default values for these arguments.
If your plugin has required arguments (plugin cannot work without those
arguments), they can be listed in the :attr:`Cell.required`
list. Using a cell without setting one of those arguments will display an
error.
For more complex cases (either `foo` or `bar` should be set; `foo` default
value is `bar` if `baz` is not set, `None` otherwise; `foo` is required only if
`bar` is not set; etc.), you have to implement it by hand in the
:meth:`Cell.render` method.
.. _errors:
Errors
^^^^^^
To display an error (both in the generated HTML page, and in the log), the
:class:`Cell` class has a :meth:`Cell.render_error` method. This is to be used
as::
class Foo(Cell):
keyword = 'foo'
def render(self, context, package, cell):
if not 'bar' in cell:
return self.render_error(context, self.keyword, package, "Error: argument 'bar' missing.")
return "<p>" + cell['bar'] + "</p>"
.. _yaml:
YAML configuration files
========================
......
......@@ -55,9 +55,18 @@ def temp_update(source, update):
class Cell:
"""Render some piece of information about a package as HTML code."""
#: Keyword referencing the plugin, used in the :ref:`yaml` file to enable
#: this plugin. If ``None``, the class is an abstract class that cannot be
#: used directly.
keyword = None
#: Title of the column.
title = ""
#: Default values for package arguments. See :ref:`defaultrequired` for more details.
default = {}
#: List of names of required package arguments. See :ref:`defaultrequired` for more details.
required = []
def __init__(self, renderer):
......@@ -88,12 +97,27 @@ class Cell:
return self.render(context, package, filled)
def render(self, context, package, cell):
"""Return the HTML code corresponding to this cell."""
"""Return the HTML code corresponding to this cell.
:param context: Current `Jinja2 context <http://jinja.pocoo.org/docs/dev/api/#jinja2.runtime.Context>`_.
:param str package: Package name.
:param dict cell: Package arguments for this cell.
:rtype: str
:return: The HTML code to display in the given cell.
"""
raise NotImplementedError()
@staticmethod
def render_error(context, cell, package, message):
"""Return the HTML code corresponding to an error."""
"""Return the HTML code corresponding to an error.
:param context: Current `Jinja2 context <http://jinja.pocoo.org/docs/dev/api/#jinja2.runtime.Context>`_.
:param str cell: Cell name (plugin keyword).
:param str package: Package name.
:param str message: Human readable error message.
:rtype: str
:return: The HTML code to display in the given cell.
"""
full_message = "Package '{}', cell '{}': {}".format(package, cell, message)
LOGGER.error(full_message)
return (
......@@ -103,7 +127,10 @@ class Cell:
)
class Jinja2(Cell):
"""Generic class for cells that are barely more than a template."""
"""Generic class for cells that are barely more than a template.
TODO Available variables
"""
def render(self, context, package, cell):
"""Return the HTML code corresponding to this cell."""
......@@ -116,5 +143,8 @@ class Jinja2(Cell):
@property
def template(self):
"""Return template path."""
"""Return template path.
TODO
"""
return os.path.join("cells", "{}.html".format(self.keyword))
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment