Commit f8e829e0 authored by Pierre Dittgen's avatar Pierre Dittgen
Browse files

Génération de la doc de configuration du badge

parent 62f3e735
# Génération de la documentation markdown
Un script Python pour générer la documentation relative à la configuration
du badge Validata.
## Pré-requis
Le script nécessite la bibliothèque `toml` et `Jinja2`. Pour les installer :
```bash
pip install -r requirements.txt
```
## Personnalisation
La structure de la page de documentation est stockée dans le fichier templace doc_md.jinja2
## Génération de la documentation
`̀̀``bash
python3 doc_gen.py ../badge_conf.md
```
# Badge Validata
## Principe
Le badge Validata est une représentation graphique destinée
à illustrer l'état de validité
d'une ressource tabulaire selon les critères de Validata.
Sa représentation s'appuie sur le descriptif des erreurs relevées par l'outil de
[validation Validata](https://go.validata.fr) pour une ressource données.
Les erreurs sont de deux types :
- structure : (nombre, ordre et libellés des colonnes)
- contenu : valeur absente, incorrecte, trop courte ou trop longue...
Les erreurs de structure sont vérifiées tout d'abord. Si la structure est incorrecte,
la validation s'arrête là. Sinon, un taux d'erreur de contenu est calculé sur la base de
```nombre de cellules en erreur / nombre de cellules total```.
Au-delà d'un certain *seuil acceptable*, la ressource n'est plus utilisable.
## Configuration
Il est possible de jouer sur :
- le seuil d'acceptabilité (`acceptability-threshold`)
- le poids accordé à chaque type d'erreur (`errors-weight`)
en modifiant le fichier [badge_conf.toml](https://git.opendatafrance.net/validata/validata-badge/blob/master/badge_conf.toml).
### Configuration actuelle
Le seuil d'acceptabilité est fixé à **{{ threshold * 100 }}%**
{% if weight_dict %}
Type(s) d'erreurs avec ayant un poids personnalisé :
{% for err, w in weight_dict|dictsort %}
- {{ err }} : **{{ w * 100}}%**
{% endfor %}
{% else %}
Aucun poids défini. Tous les types d'erreur se valent.
{% endif %}
\ No newline at end of file
#!/usr/bin/env python3
"""
Generates markdown live documentation on badge configuration
"""
import argparse
import logging
import sys
from pathlib import Path
import toml
from jinja2 import Template
def main():
"""Generates markdown doc from badge configuration file"""
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('conf_file', type=Path, help='path of badge config file')
parser.add_argument('--log', default='WARNING', help='level of logging messages')
parser.add_argument('--template', type=Path, default=Path('doc_md.jinja2'), help='doc template file')
parser.add_argument('--output', type=Path, default=None, help='output file path')
args = parser.parse_args()
numeric_level = getattr(logging, args.log.upper(), None)
if not isinstance(numeric_level, int):
raise ValueError('Invalid log level: {}'.format(args.log))
logging.basicConfig(
format="%(levelname)s:%(name)s:%(asctime)s:%(message)s",
level=numeric_level,
stream=sys.stdout, # Use stderr if script outputs data to stdout.
)
conf_file = args.conf_file
if not conf_file.exists():
parser.error("Configuration file {!r} not found".format(str(conf_file)))
template_file = args.template
if not template_file.exists():
parser.error("Template file {!r} not found".format(str(template_file)))
config = toml.load(str(conf_file))
template = Template(template_file.open('rt', encoding='utf-8').read())
result = template.render(threshold=config['body']['acceptability-threshold'],
weight_dict=config['body']['errors-weight'])
fd = sys.stdout if args.output is None else args.output.open('wt', encoding='utf-8')
print(result, file=fd)
if __name__ == '__main__':
sys.exit(main())
Jinja2==2.10
toml=0.10.0
\ No newline at end of file
Supports Markdown
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