Implementar `dpm docs` para geração de dicionário de dados do data package

[fjuniorr]

Na reunião de https://github.com/splor-mg/reunioes/issues/33 ao apresentarmos o datamart e a conexão dele com o Qlikview e PowerBI comentamos que também vamos ofertar um dicionário de dados abrangendo todos os dados ingeridos para permitir discoverability por parte dos técnicos das informações disponíveis.

Durante o trabalho de padronização dos nomes das colunas em https://github.com/splor-mg/sisor-dados/pull/7 também senti bastante falta desse dicionário e usei o snippet abaixo:

from frictionless import Package, Resource
import random

def sample_field(resource, field_name, size=3):
    return '\; '.join(random.sample(list(resource.to_petl().values(field_name)), size))

package = Package('datapackage.json')

header = ['package', 'resource', 'name', 'type', 'title', 'description', 'source', 'example']

data = [
    [package.name, resource.name, field.name, field.type, field.title, field.description, field.custom.get('source'), sample_field(resource, field.name)]
    for resource in package.resources
    for field in resource.schema.fields
]

resource = Resource(data = [header] + data)
resource.write('data-dictionary.xlsx')

[fjuniorr]

Uma versão bastante útil que consegue agrupar múltiplos data packages:

from frictionless import Package, Resource
import random
import typer
from pathlib import Path
import petl as etl

def sample_field(resource, field_name, size=3):
    return '; '.join(random.sample(list(resource.to_petl().values(field_name)), size))

def to_data_dictionary(path):
    package = Package(path)

    header = ['package', 'resource', 'name', 'type', 'title', 'description', 'source', 'example']

    data = [
        [package.name, resource.name, field.name, field.type, field.title, field.description, field.custom.get('source'), sample_field(resource, field.name)]
        for resource in package.resources
        for field in resource.schema.fields
    ]

    resource = Resource(data = [header] + data)
    result = resource.to_petl()
    return result

def main(packages: list[str]):
    data_dictionary = [to_data_dictionary(package) for package in packages]
    result = etl.cat(*data_dictionary)
    result.toxlsx(f'data-dictionary.xlsx')

if __name__ == "__main__":
    typer.run(main)

@hslinhares um exemplo do resultado é data-dictionary.xlsx. Não pretendo adicionar isso ao pacote por agora, mas dá pra usar o snippet acima.

[fjuniorr]

A interface desse comando pode ser:

dpm describe|docs

Por default ele vai criar um dicionário de dados com todos os pacotes listados em data.toml. Com:

dpm describe --packages <pkgA> <pkaB>

é possível especificar os data packages via linha de comando e o data.toml será desconsiderado. A flag --output [md, excel, html] controla o formato de exportação do dicionário de dados.

O html é especialmente interessante pra gente visualizar documentações extensas (eg. identificador_tipo_acao_cod).

Algumas propriedades que ainda precisam ser inseridas e vão demandar tratamento diferenciado entre os formatos de exportação:

• primaryKey
• foreignKey (anchors to correct cell in html)
• rdfType (link to URL)
• enum

[gabrielbdornas]

@labanca, só para registro do dia que discutimos este Issue, olhar opção de criar página HTML, exemplo utilizando mkdocs-material.