Skip to content

GitLab

Docker-in-Docker (DinD) capabilities of public runners deactivated. More info

Commit 53810cab authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Polish the user guide.

parent 3532c472
Hide whitespace changes
Inline Side-by-side
Showing with 261 additions and 255 deletions
documentations/userguide/appendix_column.rst
View file @ 53810cab
......@@ -5,18 +5,62 @@
Appendix C: Column configuration
===================================
List
----
The configuration parameter for the List column are those of the
``Ext.grid.column.Column`` class. The most important one are listed in the next
sections. Those marked with a (*) are mandatory.
Lists and 1-dim Metrics display a collection of columns.
The configuration properties of the columns are those of the
``Ext.grid.column.Column`` class. More information can be found in the ExtJS_
documentation.
The properties and their values have to follow the JSON_ syntax:
The column is by default configured to render string. It is possible to handle
``boolean``, ``date`` and ``number`` values by changing the ``xtype`` property.
The mapping between the database field and the column types is the following:
.. include:: json.txt
================ =================
Database ``xtype``
================ =================
boolean ``booleancolumn``
date / datetime ``datecolumn``
integer / float ``numbercolumn``
string (default) ``gridcolumn``
================ =================
all columns
^^^^^^^^^^^
A column contains the value of the given database field. In that first case,
the mandatory properties depend on the report and are the following:
=============== ===============
List Metric1D
=============== ===============
-- ``aggregate``
``dbfield`` ``dbfield``
``text`` ``text``
=============== ===============
A column can also contains computed values obtained by applying a mathematical
expression on the cells of the other columns. In that second case, the mandatory
property are the following and do not depend on the report:
.. list-table::
* - **Computed column**
* - ``eval``
* - ``text``
The most important properties are defined in the next sections as a function of
the column type.
.. note::
The ``Metric1D`` columns are always rendered as ``numbercolumn``.
Therefore the property ``xtype`` can be omitted.
Finally, the ExtJS_ library provide a special column numbering the rows
starting at one. It has only one configuration property:
.. code:: javascript
"xtype" : "rownumberer"
All columns
-----------
``align``
the alignment of the column.
......@@ -25,123 +69,68 @@ all columns
``columnWidth`` or ``flex``
the column width can be specified as a number or a percentage.
``dbfield`` (*)
``dataIndex``
the index of the column used by the ``DataFrame``, the ``Ext.data.store``
and the ``Ext.grid.Panel``. By default, this internal parameter is equal
to the ``text`` property. However, when using the ``eval`` property, it
could be useful to index the column with short name like *a*, *b*, ...
``dbfield``
the address of the database field encoded as ``"tablename.fieldname"`` or
``"tablename.fieldname.keyname"``.
.. warning::
Do not use with the ``rownumberer`` column.
.. warning::
Do not use with the ``eval`` property.
``eval``
the string defining the mathematical operation applied between column cells,
*e.g* ``(a+b*2)/c`` where *a*, *b* and *c* are column indexes.
.. warning::
Do not use the ``dbfield`` and ``aggregate`` properties.
``hidden``
the column is hidden when it is ``true``.
``renderer``
A string pointing to the javascript function rendering the value or
containing the function itself.
containing the function itself. The possible value is ``reprDuration``.
``text`` (*)
``text``
the string containing the label of the column.
``xtype`` (*)
``xtype``
the string specifying the type of the column.
The mapping between the type of the column and the one of the database field
is the following:
.. list-table::
* - ``booleancolumn``
- boolean
* - ``datecolumn``
- date or datetime
* - ``numbercolumn``
- integer or float
* - ``gridcolumn``
- string (default)
booleancolumn
^^^^^^^^^^^^^
Boolean column
--------------
``falseText``
the string return in the grid when the value is false.
the string returns in the grid when the value is false.
``trueText``
the string return in the grid when the value is true.
the string returns in the grid when the value is true.
datecolumn
^^^^^^^^^^
``format``
the format string, e.g. ``"d/m/Y"``.
Date column
-----------
numbercolumn
^^^^^^^^^^^^
``format``
the format string, e.g. ``"0,000.00"``.
``summaryType``
Summary over column values are computed.
Possible values are ``"count"``, ``"sum"``, ``"min"``, ``"max"`` and
``"average"``.
Metric 1D
---------
the format string, *e.g.* ``"d/m/Y"``.
The configuration parameters for the Metric1D column is similar to
those of the ``numbercolumn`` since the table only contains number. Therefore
it is not required to specify the column type.
Number column
-------------
all column
^^^^^^^^^^
``align``
the alignment of the column.
Possible values are: ``"left"``, ``"center"``, and ``"right"``.
``columnWidth`` or ``flex``
the column width can be specified as a number or a percentage.
``aggregate``
the aggregation function uses by the 1-dim metric.
Many functions are available: ``count``, ``max``, ``mean``,
``median``, ``min``, ``size``, ``std``, ``sum``, *etc*. In fact, all the
descriptive stats methods of the DataFrame_ class.
``format``
the format string, e.g. ``"0,000.00"``.
``hidden``
the column is hidden when it is ``true``.
``renderer``
the string pointing to the javascript function rendering the value or
containing the function itself.
``text`` (*)
the label of the column.
the format string, *e.g.* ``"0,000.00"``.
``summaryType``
the summary over column values are computed.
Possible values are ``"count"``, ``"sum"``, ``"min"``, ``"max"``
and ``"average"``.
``dataIndex``
the index of the column used by the ``DataFrame``, the ``Ext.data.store``
and the ``Ext.grid.Panel``. By default, this internal parameter is equal
to the ``text`` property. However, when using the ``eval`` property, it
could be useful to index the column with short name like *a*, *b*, ...
database field column
^^^^^^^^^^^^^^^^^^^^^
``aggregate`` (*)
Many aggregation functions are available: ``count``, ``max``, ``mean``,
``median``, ``min``, ``size``, ``std``, ``sum``... In fact, all the
descriptive stats methods of the DataFrame_ class.
``dbfield`` (*)
the address of the database field encoded as ``"tablename.fieldname"`` or
``"tablename.fieldname.keyname"``.
computed column
^^^^^^^^^^^^^^^
``eval`` (*)
the string defining the mathematical operation applied between column cells,
*e.g* ``(a+b*2)/c`` where *a*, *b* and *c* are column indexes.
.. warning::
Do not use the ``dbfield`` and ``aggregate`` properties.
Summary are computed over the column values.
Possible functions are ``"count"``, ``"sum"``, ``"min"``, ``"max"`` and
``"average"``.
documentations/userguide/appendix_graph.rst
View file @ 53810cab
......@@ -59,10 +59,9 @@ The basic keywords
deactivate grid (legend) when it is ``false``.
``colormap``
set the colormap indentify by its name.
Possible values in http://matplotlib.org/users/colormaps.html
set the matplotlib.colormap_ identify by its name.
``xerr`` and ``yerr``.
``xerr`` and ``yerr``
set errors bars.
``index``, ``x`` and ``y``
......@@ -82,9 +81,10 @@ The basic keywords
set the label along the *x* and *y*-axis respectively
``tranpose``
boolean value to exchange *x* and *y*-axis.
boolean value to exchange *index* and *column* using the method
``DataFrame.T``.
Column addressing
-----------------
......@@ -104,10 +104,3 @@ in columns. In order to:
* a stacked histogram/bar with the reduced set of columns, use the list::
index = [column labels, or positions]
.. note::
The column label is derived from the database field address by removing
the dot, *e.g* ``tablenamefieldname``.
.. note::
The column label can also be equal to column values.
\ No newline at end of file
documentations/userguide/appendix_virtualfield.rst
View file @ 53810cab
......@@ -8,8 +8,10 @@ Appendix B: Virtual fields
History
-------
.. tabularcolumns:: |l|l|p{9cm}|
.. list-table::
:widths: 20 10 50
:widths: 30 10 60
* -
-
......@@ -17,7 +19,7 @@ History
* - ``history.coverage``
- float
- the time coverage of the history record with respect
to the period range selected by the user. It is a value between 0 and 1.
to the period selected by the user. It is a value between 0 and 1.
* - ``history.duration``
- float
- the duration of the history record. The end date is ``now`` when
......@@ -29,14 +31,14 @@ History
person assigned to the record. It is a value between 0 and 1.
* - ``history.is_end``
- boolean
- Return true is the history record ends during the period range selected
- Return true is the history record ends during the period selected
by the user.
* - ``history.is_over``
- boolean
- Return true is the history record is over ``now``.
* - ``history.is_start``
- boolean
- Return true is the history record starts during the period range
- Return true is the history record starts during the period
selected by the user.
People
......@@ -56,7 +58,7 @@ Time axis
---------
The ``time`` is not a field of the ``history`` table since a time period is
associated to each event. However, mechanism has been introduce to extract the
associated to each event. However, mechanism has been introduced to extract the
database information on a year basis. Therefore the pseudo field ``year`` can
be used in the reporting.
......
documentations/userguide/conditions.txt
View file @ 53810cab
......@@ -5,14 +5,17 @@ The fitler conditions is defined in the ``General`` tab.
The ``Conditions`` are used to select a sub-sample of the history records. It
is based on the smart_query_ available in the Web2py_ framework. The query
is written in the natural language, but it is limited to field of the
history table. Foreign tables fields, virtual fields or keys of the
``history.data`` dictionary can not be used.
history table.
The ``changelog`` event introduced earlier has the ``id`` equal to 7. To
select history related changelog events, enter:
.. warning::
Do not use foreign fields, virtual fields, keys of the
``history.data`` dictionary as well as the pseudo field year.
Example of smart query:
.. code::
history.id_events = 7
history.id_events = 7 and id_people_categories not in 1,11,13,14
Possible operators are given :ref:`Appendix E`.
documentations/userguide/conf.py
View file @ 53810cab
......@@ -44,7 +44,8 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'track_events'
app = unicode(os.getcwd().split(os.sep)[-3])
project = app
copyright = u'2015, R. Le Gac'
# The version info for the project you're documenting, acts as replacement for
......@@ -177,7 +178,7 @@ html_static_path = ['_static']
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'track_eventsdoc'
htmlhelp_basename = '%sdoc' % app
# -- Options for LaTeX output --------------------------------------------------
......@@ -196,7 +197,7 @@ latex_elements = {
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'track_events.tex', u'track\\_events Documentation',
('index', '%s.tex' % app, u'%s documentation' % app.replace('_', '\\_'),
u'R. Le Gac', 'manual'),
]
......@@ -226,7 +227,7 @@ latex_use_parts = False
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'track_events', u'track_events Documentation',
('index', str(app) , u'%s Documentation' % app,
[u'R. Le Gac'], 1)
]
......@@ -240,8 +241,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'track_events', u'track_events Documentation',
u'R. Le Gac', 'track_events', 'One line description of project.',
('index', str(app), u'%s Documentation' % app,
u'R. Le Gac', str(app), 'One line description of project.',
'Miscellaneous'),
]
......
documentations/userguide/dbfields.rst
View file @ 53810cab
......@@ -6,26 +6,29 @@ Addressing database fields
.. _database-figure:
.. figure:: ../../static/docs/database.png
:align: center
:width: 90%
:align: center
:width: 90%
The database scheme.
The database scheme. Events are stored in the history and linked tables.
The remaining tables store the configurations for the report objects.
The fields of the database and their relations are shown in the
:num:`Fig. #database-figure` and summarized in the :ref:`Appendix A`. The
``history`` and
``people`` table contains also virtual fields. Their values are not stored in
the database but computed, on-demand, for each request. Their definitions are
given in the :ref:`Appendix B`.
:num:`Fig. #database-figure` and summarized in the :ref:`Appendix A`.
The ``history`` and ``people`` table contains also virtual fields. Their values
are not stored in the database but computed, on-demand, for each request and
can be used in reports. Their definitions are given in the :ref:`Appendix B`.
Basic field type
----------------
The basic field contains ``blob``, ``boolean``, ``date``, ``datetime``,
``double``, ``float``, ``integer``, ``string``, ``text`` and ``time`` values.
The addressing of these field follows the usual rules::
The addressing of these field follows the usual rules:
.. code:: python
tablename.fieldname
tablename.fieldname
JSON field type
----------------
......@@ -35,9 +38,11 @@ JSON_ serializable object. It is used to store python dictionary in the
``events.data`` and ``history.data`` fields.
Reports have to access to any dictionary key. In that case, the address is
given by::
given by:
tablename.fieldname.keyname
.. code:: python
tablename.fieldname.keyname
The pseudo field "year"
-----------------------
......@@ -46,6 +51,8 @@ An event spans over a period of time defined by the *history.start_date* and
*history.end_date* fields. This period can cover several years. Although the
year is not a field of the ``history`` table, a mechanism has been introduced to
sample the database information on a year basis. It is activated via the
address of the pseudo field::
address of the pseudo field:
.. code:: python
year
\ No newline at end of file
year
\ No newline at end of file
documentations/userguide/event.rst
View file @ 53810cab
......@@ -4,82 +4,86 @@ Events
=======
This applications record events. It can happen at a date or span during a
period of time. An event is the relation between a person and a team /
project. When he/she arrive, left. How many time does he/she spent. It can also
be an entry in a changelog. Why and when the content of the database has been
modified. In fact, there are no limitation on the events which can be tracked.
period of time.
An event is defined by a *starting date*, by an *ending date* and by a *name*.
An event is defined by a *starting date*, by an *ending date* and by a *type*.
An event contains *meta-data* linking the event to:
* a person
* a teams
* a team
* a project
* a category (the category of people in this application)
* a funding agency
The event are stored in the ``history`` table and the meta-data in the foreign
The events are stored in the ``history`` table and the meta-data in the foreign
tables ``fundings``, ``people``, ``people_categories``, ``projects`` and
``teams``. The organization of the table can not be changed. All the fields of
these tables are standard database field. They can be used in standard SQL
request or in reports.
these tables are standard database field which can be used in SQL request or in
reports.
An event contains also a *user data block*. It is stored in one database field.
The user data block is a python dictionary serialized as a JSON_ string.
An event contains also the *user data block*. It is stored in one database
field. The user data block is a python dictionary serialized as a JSON_ string.
The structure of the dictionary, *the keys*, are defined by the user, once, for
each event type. The structure of the dictionary can be modified at any
time by the user. Mechanisms are in placed to guaranty the consistency across
the database. The SQL Request are limited to string operations.
Individual key of the dictionary can not be used. But, any key can be used in
reports.
the database. The SQL request are limited to string operations.
Individual key of the dictionary can not be used in SQL request. But, any key
can be manipulated in reports.
How to define an event
----------------------
Define an event
----------------
The event definitions are stored in the ``events`` table.
In order to create a new event definition:
1. open the leaf ``events > definition`` in the left panel of the
1. Open the leaf ``events > definition`` in the left panel of the
viewport.
2. right click anywhere in the right panel
3. select the menu item ``Add``
2. Open the contextual menu in the right panel.
3. Select the menu item ``Add``.
.. figure:: figures/event-form.png
:align: center
:width: 50%
.. figure:: figures/event-form.png
:align: center
:width: 50%
The form to enter an event definition in the database.
The form to enter an event definition in the database.
4. Enter the event name in the ``event`` entry.
4. Enter the event type in the ``event`` entry.
5. Enter the python dictionary structure in the ``model`` field.
Add the first key by right clicking on ``property`` label. Later on,
Key can be ``Add``, ``Modify`` or ``Delete`` using the
key can be ``Add``, ``Modify`` or ``Delete`` using the
contextual menu.
.. warning::
the data user block of all the existing events are modified when the
the data user block of the existing events are updated when the
python dictionary structure is modified.
A good practice is to enter the type of key (``boolean``,
``date``, ``string``, ``number``) or a default value.
How to enter an event
----------------------
Enter an event in the history
------------------------------
The events of any kind are stored in the ``history`` table.
Events of any kind are stored in the ``history`` table.
In order to create a new one:
1. open the leaf ``events > history`` in the left panel of the
1. Open the leaf ``events > history`` in the left panel of the
viewport.
2. right click anywhere in the right panel
3. select the menu item ``Add``
2. Open the contextual menu in the right panel.
3. Select the menu item ``Add``.
.. figure:: figures/history-form.png
:align: center
:width: 50%
.. figure:: figures/history-form.png
:align: center
:width: 50%
The form to enter an event in the database.
The form to enter an event in the database.
4. Scan the different tabs and fill the appropriate entries.
Make report on events
----------------------
The application provides a rich set of tools to configure and to
produce reports. They are covered in the Chapters :ref:`Configure the lists`,
:ref:`Configure the 1-dim metrics` and :ref:`Configure the 2-dim metrics`
\ No newline at end of file
documentations/userguide/graph.rst
View file @ 53810cab
.. include:: hyperlinks.txt
How to configure a graph
==========================
Configure the graphs
=====================
Any data encapsulated in list, 1-dimension or 2-dimension metrics can be
Any data encapsulated in list, 1-dim or 2-dim metrics can be
displayed as a graph. The rendering is performed by the matplotlib_ library.
Therefore, many representations of the data are possible: plot, histogram, bar
charts, errorcharts, scaterplots, etc.
The configuration of each graph is stored in the database. It
defines the link between the graph and the list / metric as well as how to
display the data. In order to create a new one:
display the data.
#. open the leaf ``configure > the graph`` in the left panel of the
In order to create a new one:
#. Open the leaf ``configure > the graph`` in the left panel of the
viewport.
#. open contextual menu in the right panel.
#. select the menu item ``Add``
#. Open contextual menu in the right panel.
#. Select the menu item ``Add``.
.. _graph-form-figure:
......
documentations/userguide/hyperlinks.txt
View file @ 53810cab
..
The collection of hyperlinks used in the different section
.. _DataFrame: http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe
.. _DataFrame.plot:
......@@ -13,6 +14,8 @@
.. _matplotlib: http://matplotlib.org/
.. _matplotlib.colormap: http://matplotlib.org/users/colormaps.html
.. _matplotlib.pyplot: http://matplotlib.org/api/pyplot_summary.html
.. _pandas: http://pandas.pydata.org/pandas-docs/stable/
......
documentations/userguide/list.rst
View file @ 53810cab
.. include:: hyperlinks.txt
How to configure a list