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

Commit c7f46f28 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Improve documentation.

parent e9a7529b
......@@ -11,6 +11,7 @@ databases*/
*build*
*jsduck*
*epydoc*
*sphinx*
errors/
private/
*plugin_ace*
......
......@@ -52,7 +52,8 @@ JSDOC = 'static/docs/jsduck'
JSLIBMIN = 'static/%s-min.js' % APP
JSLIBSRC = 'static/src'
PYDOC = 'static/docs/epydoc'
SPHINXDIR = 'static/docs/userguide/'
SPHINXDOC = 'static/docs/sphinx'
SPHINXSRC = 'documentations/userguide/'
NOW = datetime.datetime.now()
......@@ -60,6 +61,7 @@ NOW = datetime.datetime.now()
JSDUCK = os.path.expandvars("$HOME/bin/jsduck")
GIT = '/usr/bin/git'
SENCHA = os.path.expandvars("$HOME/bin/sencha")
SPHINX = '/usr/bin/sphinx-build'
# message
MSG_VERSION = 'Enter the new version: '
......@@ -250,22 +252,20 @@ def sphinx():
"""Generate the Sphinx documentation.
"""
# protection
if not os.path.exists(SPHINXDIR):
if not os.path.exists(SPHINX):
print '\n\tThe application sphinx is missing !'
print '\tSkip this step.\n'
return
# current working directory
cwd = os.getcwd()
# move to the sphinx directory and run the make command
os.chdir(SPHINXDIR)
cmd = ["make", "html"]
print 1, SPHINXSRC
if not os.path.exists(SPHINXSRC):
return
cmd = [SPHINX, "-b", "html", SPHINXSRC, SPHINXDOC]
print 2, cmd
subprocess.call(cmd)
# go back to current directory
os.chdir(cwd)
print "Sphinx documentation in", "%s/buid" % SPHINXDIR
print "Sphinx documentation in", SPHINXDOC
if __name__ == '__main__':
......
......@@ -2,5 +2,6 @@
.. _Appendix D:
Appendix D: Plot configuration
Appendix D: Graph configuration
===================================
......@@ -13,6 +13,10 @@
import sys, os
import subprocess
import tempfile
import re
# 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.
......@@ -47,10 +51,19 @@ copyright = u'2015, R. Le Gac'
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# -- recuperate the version/release from git
fi = tempfile.TemporaryFile()
subprocess.call(["git", "describe", "--tags"], stdout=fi)
fi.seek(0)
myrelease = fi.read()
fi.close()
# The short X.Y version.
version = '0.3'
version = re.match('\d+\.\d+', myrelease).group()
# The full version, including alpha/beta/rc tags.
release = '0.3.0-86'
release = myrelease
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......
......@@ -5,7 +5,7 @@ Addressing database fields
.. _Fig 3:
.. figure:: ../../database.png
.. figure:: ../../static/docs/database.png
:align: center
:width: 90%
......@@ -30,10 +30,21 @@ JSON field type
----------------
The Web2py_ framework introduces the additional type ``json`` which can store
JSON_ serializable object. It is used, in this application, to store python
dictionary. This is the case of ``events.data`` and ``history.data`` fields.
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::
tablename.fieldname.keyname
The pseudo field "year"
-----------------------
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::
year
\ No newline at end of file
.. include:: hyperlinks.txt
How to configure a graph
==========================
Any data encapsulated in list, 1-dimension or 2-dimension 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:
#. 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``
.. _Fig 10:
.. figure:: figures/graph-form.png
:align: center
:width: 50%
Figure 10
The configuration form, shown in :ref:`Fig 10`, contains two tabs:
.. list-table::
:widths: 10 70
* - ``General``
- the name of the graph, the title of the report and the
link to the list / metrics.
* - ``Configure``
- the configuration of the graph.
Details are given in the next subsections.
General
-------
The link to the ``list`` or ``metrics`` is defined by the two entries
``Report type`` and ``Report name``. The latter has to be equal to a list or
metric name.
Configure
---------
The configuration of the graph is defined in the ``Configure`` tab. It has a
single entry which has to be filled with an ``object``. The language used is
JSON_ in which:
.. include:: json.txt
The graph can be a displayed as a plot, an histogram, a stacked bar char, ...
It is rendered by the matplotlib_ library through the ``plot`` method of the
DataFrame_ class. The method has many keywords allowing to select the
graph type and to tune its rendering. The properties of the object correspond
to the keyword, value pairs of the plot method. Detailed description can be
found in `DataFrame.plot`_ documentation or in :ref:`Appendix D`.
..
..
The collection of hyperlinks used in the different section
.. _DataFrame: http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe
.. _DataFrame.plot:
http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.plot.
html#pandas.DataFrame.plot
.. _ExtJS: http://docs-origin.sencha.com/extjs/4.2.1/#!/api
.. _JSON: http://www.json.org/
.. _Pandas: http://pandas.pydata.org/pandas-docs/stable/
.. _matplotlib: http://matplotlib.org/
.. _pandas: http://pandas.pydata.org/pandas-docs/stable/
.. _smart_query: http://web2py.com/books/default/chapter/29/06/the-database-
abstraction-layer#smart_query--experimental
.. _Web2py: http://web2py.com/
Markdown is supported
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