YAML configuration files

Some plugins try to guess the appropriate required values, but it is not always possible. For instance, plugin readthedocs cannot guess the documentation URL, since it can differ from http://<PypiPackageName>.readthedocs.io (for instance, the documentation URL of sphinxcontrib-packages is http://packages.readthedocs.io and not http://spinxcontrib-packages.readthedocs.io). Thus, it may be necessary to provide additional information. This can be done using YAML files.

Processing YAML files

Configuration files can be processed by both pypimonitor command line interface, and by the pypimonitor.httpd web sever. See the relevant documentation for more information.

Writing YAML files

Example

The example page is produced using the following YAML file:

 1default:
 2  CI:
 3    cell: gitlabci
 4    server: //framagit.org
 5    user: spalax
 6  Coverage:
 7    cell: gitlabcoverage
 8    server: //framagit.org
 9    user: spalax
10cells:
11  - color
12  - homepage
13  - pypiversion
14  - pythonversions
15  - pypimdownloads
16  - pypiwdownloads
17  - pypiddownloads
18  - readthedocs
19  - CI
20  - Coverage
21packages:
22  argdispatch:
23  annales-math:
24    homepage:
25      homepage: //framagit.org/lpaternault/annales-math
26    CI:
27      cell: gitlabci
28      server: //framagit.org
29      user: lpaternault
30    Coverage:
31      cell: gitlabcoverage
32      server: //framagit.org
33      user: lpaternault
34  cahier:
35  chval:
36  clachievements:
37  devoir:
38  dummypdf:
39  evariste:
40  fullcoverage:
41  jouets:
42  mklog:
43  papersize:
44  paste2sms:
45  pdfautonup:
46  pdfimpose:
47  pdfimpose-web:
48  pypimonitor:
49  scal:
50  sphinxcontrib-packages:
51    readthedocs:
52      slug: packages
53  sphinxcontrib-proof:
54  sphinxcontrib-stuffcounter:
55    homepage:
56      homepage: //framagit.org/spalax/sphinxcontrib-stuffcounter
57  spix:
58  squelette:
59  toto2titi:
60    CI:
61      cell: gitlabci
62      server: //framagit.org
63      user: spalax
64      slug: paste2sms
65    Coverage:
66      cell: gitlabcoverage
67      server: //framagit.org
68      user: spalax
69      slug: paste2sms
70    readthedocs:
71      slug: paste2sms

Configuration options

The YAML configuration is a dictionary, with the following keys : default, cells, packages. There can be additionnal keys, used by somme cell plugins (at the time I am writing this, no plugin uses this).

In the following example, the YAML configuration file is reffered as a Python dict.

cell option

The cell plugin used to render column foo of line mypackage is the plugin having as keyword (by order of precedence):

  • value of config[‘packages’][‘mypackage’][‘foo’][‘cell’] (to explicitely set the plugin to use for a single package);

  • value of config[‘default’][‘foo’][‘cell’] (to explicitely set the default plugin to use for a whole column);

  • foo (at last, the column reference is used as the cell plugin keyword);

  • the default error plugin.

packages

This is a dictionary of dictionaries: the keys are the pypi package names, and the values are either nothing (if the default values are sufficient to process this package), or a dictionary of cell options: the keys of this “sub-dictionary” are the cell names, and the values are dictionary of cell options.

For instance, in the example:

cells

If config[‘cells’] is not defined, the list of columns is deduced from the cells used in the package options. This option has two purposes:

  • explicitely set the list of columns (for instance, in the example, since color is never referenced in package options (every package use the default options for this plugin), it would not appear in the generated HTML file if it were not present in the config[‘cells’] list);

  • set the order of those columns.

The values of this list can be:

  • a cell plugin keyword, in which case, unless otherwise specified, the plugin used to render this cell is the corresponding plugin, and the title of the column is the title of this plugin;

  • or an arbitrary text, in which case each package has to explicitely define its cell plugin for this cell, or the cell plugin to use has to be defined in the default value (see default).

default

Default cell parameters can be set, and apply to every package (unless a different parameter is set specifically for this program). This option is a dictonary, where:

  • keys are the column names (as referenced in the cells option);

  • values are dictionary of options, which are applied to every package, unless the package explicitely specified a different option.

For instance, in the example the default configuration contains:

CI:
  cell: gitlabci
  server: http://framagit.org
  user: spalax

This means that, unless a package specifies something else: