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:
package fullcoverage uses only default values, so it is mentionned without options;
however, package sphinxcontrib-packages has, as a value,
{'readthedocs': {'slug': 'packages'}}
, which means that options{'slug': 'packages'}
is passed to the readthedocs plugin (which means that the documentation URL is http://packages.readthedocs.io instead of http://sphinxcontrib-packages.readthedocs.io).
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:
the plugin used to render the cells is gitlabci;
the gitlab server is http://framagit.org (and not the plugin default http://gitlab.com);
the user is spalax.