search

digital-guard / preserv

Digital Preservation Project
http://git.digital-guard.org/preserv
Apache License 2.0
0 stars 0 forks source link

Melhoras no template de README #9

Open ppKrauss opened 3 years ago

ppKrauss commented 3 years ago

Sobre instruções: citar que vai entrar com o novo make me, e que basta make que vai indicar make readme.

Sobre segurança: avisar que já existe ou simplesmente fazer um mv forçado para README.backup para não haver risco

Indicar aqui nesta issue novas solicitações: por exemplo SRID, nomes de layer, nomes de file, e listagem nomes de coluna.

ppKrauss commented 2 years ago

@0e1 podemos retomar?

crebollobr commented 2 years ago

Acho que podemos deixar essa issue congelada, o @luisfelipebr está fazendo os README.md e eu depois fazendo os make_conf.yaml

ppKrauss commented 2 years ago

Hora de retomar... Vamos listar todas as pendências e decisões depois de reunião.

Notamos que não é qualquer um que consegue receber dados e fazer o Readme... E que a "capacitação em make_conf" não requer muito mais que a "capacitação em Readme". Tendo isso em vista, talvez não faça mais sentido pedir para que criem e editem os dois arquivos, bastaria um... Então está será a decisão mais importante a ser toamada, seguir uma ou outra estratégia:

  1. Continuar usando dois arquivos, e continuar com o risco de Readme e make_conf perderem a consistência entre si.
    Ou podemos simplificar o Readme e deixar que todo o resto seja preenchido automatizamente pelo make_conf. Algo como marcas de header e footer para controlar onde no inicio e onde no fim entram os dados do make_conf.

  2. Mudar o procedimento, focamos apenas no make_conf, deixando que o Readme seja 100% gerado por computador. Nesse caso acrescentariamos mais campos no make_conf, para fazer comentários livres ou acrescentar seções de observações. Ultimo caso, se editar YALM for muito chato, dar a liberdade de criar um arquivo include.md.

0e1 commented 2 years ago

Exemplo de yaml com as chaves definidas: https://github.com/digital-guard/preserv/wiki/Extens%C3%A3o-do-make_conf/00e47aa34bb9f4ad148f729ab36d4ac7e39f4bbe

Além disso, attachment.md foi o nome definido para conter tudo aquilo que não se encaixar nas novas chaves.

luisfelipebr commented 2 years ago

Utilizando exemplo: (1) Atibaia - SP https://github.com/digital-guard/preserv-BR/blob/main/data/SP/Atibaia/_pk0021.01/make_conf.yaml

crebollobr commented 2 years ago

Esses novos atributos foram implementados?

ppKrauss commented 2 years ago

Esses novos atributos foram implementados?

Sim, e creio que essa semana teremos uma primeira versão do template.... @0e1 , estamos quase lá?

Os próximos passos são:

  1. Fechar estrutura geral HTML dos templaples
  2. Testar para os exemplos indicados, tais como Atibaia, e passar por um primeiro ciclo de revisão e aprovação.
  3. Fechar com ajustes de CSS, e separação de dois tipos de template: um para "make_conf maduro" (template mais completo e complexo), outro para make_conf imaturo, com estrutura mais simplificada.
0e1 commented 2 years ago

Vejam exemplo de readme gerado em https://github.com/digital-guard/preserv-BR/blob/main/data/SP/Atibaia/_pk0021.01/README-draft.md. Foram utilizados https://github.com/digital-guard/preserv-BR/blob/main/data/SP/Atibaia/_pk0021.01/make_conf.yaml e https://github.com/digital-guard/preserv-BR/blob/main/data/SP/Atibaia/_pk0021.01/attachment.md como arquivo de anexos.

Para realizar testes, tomar como exemplo:

pushd /var/gits/_dg/preserv/src
make ini_ingest pg_db=ingest42
pushd /var/gits/_dg/preserv-BR/src
make all
pushd /var/gits/_dg/preserv-BR/data/SP/Atibaia/_pk0021.01
make readme pg_db=ingest42
cat README-draft.md

O template está em https://github.com/digital-guard/preserv-BR/blob/main/src/maketemplates/readme.mustache.

Com isso, podemos seguir os próximos passos.

Notar que:

ppKrauss commented 2 years ago
Company Contact Country
Alfreds Futterkiste Maria Anders Germany
Centro comercial Moctezuma Francisco Chang Mexico

usar aside com css inline parece não funcionar no github;

Olá! @0e1 , isso funciona sim!

Como comentei antyes, é simples <table align="right">

0e1 commented 2 years ago

Fonte para template do preserv-BR: https://github.com/digital-guard/preserv-BR/blob/main/src/maketemplates/readme.mustache

Resultado em Atibaia (com tabela à direita):

ppKrauss commented 2 years ago

@0e1 acrescentei alterações para exemplificar: https://github.com/digital-guard/preserv-BR/commit/e1c11bc82156728913c3b5997f4286cb98120a8d

Depois da (nova) seção de Reprodutibilidade, acrescentar o relatório de erros e repetições. Se houverem mais estatisticas, tais como a "assinatura de geohashes", também acrescentar nessa seção final.

0e1 commented 2 years ago

  • acrescentar MiB no tamanho do arquivo

  • usar #### ao invés de ### nas seções de "Dados relevantes" e "publicados"

  • separar com max de 2 linhas se posível

  • texto em markdown dispensa link por <a href etc></a> , basta a URL

  • arredondar tudo para 2 casas, exceto densidade que podem ser 4 casas

Atendi todos os itens, exceto a separação com duas linhas.

Ver os exemplos: https://github.com/digital-guard/preserv/blob/main/docs/pt/new_readme.md#exemplos

0e1 commented 2 years ago

separar com max de 2 linhas se posível

Isso foi resolvido aplicando um regex antes do texto do readme ser escrito no sistema de arquivos.

Depois da (nova) seção de Reprodutibilidade, acrescentar o relatório de erros e repetições. Se houverem mais estatisticas, tais como a "assinatura de geohashes", também acrescentar nessa seção final.

A seção de reprodutibilidade foi implementada. Exemplos podem ser vistos nos pacotes citado no link https://github.com/digital-guard/preserv/blob/main/docs/pt/new_readme.md#exemplos. Exigiu que tudo fosse movido para o optim. Concentrei tudo o que é relacionado a geração de makefile/readme em optim-step7-make.

Relatorios de erros e repetições e demais estátisticas ainda não foram adicionadas.

Os comandos de cada pacote podem ser vistos na view optim.reproducibility da dl03t_main.

0e1 commented 2 years ago

Exemplo de valor da coluna lineage e kx_profile em optim.donated_packcomponent. Dados que ainda podem ser consumidos no readme são: statistics (de ingestão), ghs_signature, ghs_info_mosaic, ghs_distrib_mosaic

{"file_meta": {"file": "/tmp/sandbox/_pkBR421_001/rb_20201111/quadras.shp", "size": 6231008, "isdir": false, "access": "2022-05-24T22:32:55-03:00", "change": "2022-05-24T22:32:55-03:00", "creation": null, "modification": "2020-11-11T13:07:32-03:00"}, "statistics": [21430, 0, 43, 0, 0, 1, 0, 0, 0, 0, 4866, 44, 4, 4, 2, 4864], "ghs_signature": {"6qp": 2767, "6qpz0": 760, "6qpz2": 1337}, "feature_asis_summary": {"n": 4864, "size": 74, "n_unit": "polygons", "bbox_km2": 1029, "size_mdn": 0.007, "size_unit": "km2"}, "hcode_signature_parameters": {"p_heuristic": 1, "p_percentile": 0.75}, "hcode_distribution_parameters": {"p_heuristic": 3, "p_threshold": 100000, "p_threshold_sum": 3000000}}   
{"date_aprroved": "2022-05-28T20:44:17-03:00", "date_generation": "2022-05-25T17:06:55-03:00", "ghs_info_mosaic": {"6qp": {"area": 6142233016.424897, "size": 27.722125911196247, "ghs_len": 3, "area_km2": 6142.233016424897, "ghs_area": 6142.233016424897, "ghs_bytes": 2856101, "ghs_items": 1507, "size_unit": "km2", "ghsval_unit": "bytes", "val_density_km2": null, "ghs_itemsDensity": 0.2453505094922552, "size_unitDensity": 0.004513362784685102}, "6qpz": {"area": 689770508.6918811, "size": 27.975761849586615, "ghs_len": 4, "area_km2": 689.7705086918811, "ghs_area": 689.7705086918811, "ghs_bytes": 2532891, "ghs_items": 2020, "size_unit": "km2", "ghsval_unit": "bytes", "val_density_km2": null, "ghs_itemsDensity": 2.928510242965939, "size_unitDensity": 0.04055807184717334}, "6qpz2": {"area": 23422728.932375908, "size": 15.306718004995368, "ghs_len": 5, "area_km2": 23.422728932375907, "ghs_area": 23.422728932375907, "ghs_bytes": 1457715, "ghs_items": 1337, "size_unit": "km2", "ghsval_unit": "bytes", "val_density_km2": null, "ghs_itemsDensity": 57.081307812598254, "size_unitDensity": 0.6534984906834558}}, "ghs_distrib_mosaic": {"6qp": 1507, "6qpz": 2020, "6qpz2": 1337}, "publication_summary": {"size": 71.00460576577822, "bytes": 6846707, "itens": 4864, "size_unit": "km2", "avg_density": 0.23285664177177143, "size_unitDensity": 0.6985699253153143}}
ppKrauss commented 1 year ago

Foi finalizado aqui? o que temos ainda de decisões pendentes? Exemplo

0e1 commented 1 year ago

Relatorios de erros e repetições e demais estátisticas ainda não foram adicionadas.

Exceto por isso, aqui finalizado. Não foi feito porque em algum momento foi decidido não incluir, não lembro exatamente quando.