Polish the user guide.

documentations/userguide/appendix_column.rst

@@ -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 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:
+
+        ================    =================
+        Database            ``xtype``
+        ================    =================
+        boolean             ``booleancolumn``
+        date / datetime     ``datecolumn``
+        integer / float     ``numbercolumn``
+        string (default)    ``gridcolumn``
+        ================    =================
+
+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:
 
-The properties and their values have to follow the JSON_ syntax:
+    .. list-table::
+
+        * - **Computed column**
+        * - ``eval``
+        * - ``text``
+
+The most important properties are defined in the next sections as a function of
+the column type.
+
+    .. note::
 
-.. include:: json.txt
+        The ``Metric1D`` columns are always rendered as ``numbercolumn``.
+        Therefore the property ``xtype`` can be omitted.
 
-all columns
-^^^^^^^^^^^
+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.
+            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"``.
+    the format string, *e.g.* ``"d/m/Y"``.
 
-``summaryType``
-    Summary over column values are computed.
-    Possible values are ``"count"``, ``"sum"``, ``"min"``, ``"max"`` and
-    ``"average"``.
-
-Metric 1D
----------
-
-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.
-
-all column
-^^^^^^^^^^
+Number 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

@@ -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,7 +81,8 @@ 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

@@ -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

@@ -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

@@ -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

@@ -9,21 +9,24 @@ Addressing database fields
     :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
 
@@ -35,7 +38,9 @@ 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:
+
+    .. code:: python
 
         tablename.fieldname.keyname
 
@@ -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

documentations/userguide/event.rst

@@ -4,47 +4,44 @@ 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
@@ -52,29 +49,29 @@ In order to create a new event definition:
 
            The form to enter an event definition in the database.
 
-    4. Enter the event name in the ``event`` entry.