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  ferronier:
 42    CI:
 43      cell: gitlabci
 44      server: //forge.apps.education.fr
 45      user: ferronier
 46      slug: ferronier
 47    Coverage:
 48      cell: gitlabcoverage
 49      server: //forge.apps.education.fr
 50      user: ferronier
 51      slug: ferronier
 52  ferronier-gitlab:
 53    CI:
 54      cell: gitlabci
 55      server: //forge.apps.education.fr
 56      user: ferronier/plugins
 57      slug: ferronier-gitlab
 58    Coverage:
 59      cell: gitlabcoverage
 60      server: //forge.apps.education.fr
 61      user: ferronier/plugins
 62      slug: ferronier-gitlab
 63  ferronier-searchsortfilter:
 64    CI:
 65      cell: gitlabci
 66      server: //forge.apps.education.fr
 67      user: ferronier/plugins
 68      slug: ferronier-searchsortfilter
 69    Coverage:
 70      cell: gitlabcoverage
 71      server: //forge.apps.education.fr
 72      user: ferronier/plugins
 73      slug: ferronier-searchsortfilter
 74  ferronier-yaml:
 75    CI:
 76      cell: gitlabci
 77      server: //forge.apps.education.fr
 78      user: ferronier/plugins
 79      slug: ferronier-yaml
 80    Coverage:
 81      cell: gitlabcoverage
 82      server: //forge.apps.education.fr
 83      user: ferronier/plugins
 84      slug: ferronier-yaml
 85  jouets:
 86  mklog:
 87  papersize:
 88  paste2sms:
 89  pdfautonup:
 90  pdfimpose:
 91  pdfimpose-web:
 92  pypimonitor:
 93  scal:
 94  sphinxcontrib-packages:
 95    readthedocs:
 96      slug: packages
 97  sphinxcontrib-proof:
 98  sphinxcontrib-stuffcounter:
 99    homepage:
100      homepage: //framagit.org/spalax/sphinxcontrib-stuffcounter
101  spix:
102  squelette:
103  toto2titi:
104    CI:
105      cell: gitlabci
106      server: //framagit.org
107      user: spalax
108      slug: paste2sms
109    Coverage:
110      cell: gitlabcoverage
111      server: //framagit.org
112      user: spalax
113      slug: paste2sms
114    readthedocs:
115      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: