Pular para o conteúdo principal

@elucidario/pkg-pub-gen

Gerador de publicações para o Elucidário.art.

Seu principal objetivo é manter as publicações relacionadas ao Elucidário padronizadas e organizadas no monorepo do Elucidário.art.

Funcionalidades

Presets

Possui um sistema de presets para definição de qual padrão de publicação deve ser usado. Atualmente existem dois presets:

  • abnt - Padrão de publicação para o Brasil
  • apa - Padrão de publicação para os Estados Unidos e outros países

Os presets são utilizados para formatar o arquivo .docx gerado seguindo as normas estipuladas em cada padrão. Os presets também definem o formato das referências na publicação.

Internacionalização

As publicações geradas pelo pub-gen são internacionalizadas. O pub-gen cria uma pasta para cada idioma definido na publicação. Por padrão o pub-gen cria as pastas pt-br e en-us para os idiomas português e inglês respectivamente.

Referências

O pub-gen possui um sistema de referências que permite adicionar referências em um arquivo .json e gerar automaticamente as referências no formato definido pelo preset da publicação. Utiliza o citeproc-js para gerar as referências.

Padrões comuns

O pub-gen utiliza padrões comuns relacionados a publicações como

  • Data Package para descrever os metadados da publicação e os metadados dos arquivos gerados e utilizados pela publicação.
  • CSL json para descrever as referências.

Pandoc

O pub-gen utiliza o pandoc para converter os arquivos .md em .docx ou outras extensões. O pandoc é uma ferramenta de conversão de documentos de código aberto e gratuita.

Versionamento semântico

Para mais informações confira a página Versionamento.

Tabelas


Configurando o pub-gen no monorepo

Na raiz do monorepo crie um arquivo pub-gen-config.json com o seguinte conteúdo:

{
"publications": "<caminho-para-a-pasta-de-publicacoes>",
"references": "<caminho-para-a-pasta-de-referencias>"
}

O pub-gen utilizará as configurações desse arquivo para criar as publicações e referências. Você também pode utilizar o comando pnpm pub-gen init para criar o arquivo pub-gen-config.json automaticamente.


Como usar

Na raiz do elucidario execute:

pnpm pub-gen <command> <options>

Comandos

init

pnpm pub-gen init <options>

Cria o arquivo pub-gen-config.json na raiz do monorepo.

options

  • -f, --force: Força a criação do arquivo pub-gen-config.json mesmo que ele já exista.
  • -d, --default: Cria o arquivo pub-gen-config.json com as configurações padrões.

create

pnpm pub-gen create

Cria uma nova publicação. Utiliza o schema pub-gen-schema.json para criar e validar as respostas do prompt. O comando irá realizar uma série de perguntas na cli que serão utilizadas para gerar a publicação. O comando irá criar uma pasta com o nome e os arquivos necessários para a publicação na pasta publications definida no pub-gen-config.json.


reference

pnpm pub-gen reference <command>

Comandos relacionados a referências:

add

pnpm pub-gen reference add <options>

Adiciona uma nova referência. Utiliza o schema reference-schema.json para criar e validar as respostas do prompt. Este comando irá realizar uma série de perguntas na cli que será utilizada para criar uma nova referência. A referência será criada na pasta references definida no pub-gen-config.json. Para saber mais sobre como criar e editar referências veja a página Referências.

options
  • -p, --publication: Nome da publicação que a referência será adicionada. Se não passada será adicionada somente na pasta references do monorepo.
pnpm pub-gen reference search <options>

Busca uma referência na pasta references definida no pub-gen-config.json.

options
  • -p, --publication: Nome da publicação que a referência será pesquisada. Se não passada será pesquisada somente na pasta references do monorepo.
  • -t, --type: Tipo de campo que será pesquisado. Se não passado será pesquisado em todos os campos.
  • -v, --value: Valor que será pesquisado. Se não passado será retornado um erro.

index

pnpm pub-gen reference index

Usado internamente somente pelo pub-gen. Cria um arquivo na pasta root do pub-gen com o nome indexsearch.js que contém uma série de search.addIndex() para ser utilizado na busca.


add-author

pnpm pub-gen add-author <options>

Adiciona um novo autor.

options

  • -p, --publication: Nome da publicação em que o autor será adicionado. Se não passada o comando retorna um erro.

build

pnpm pub-gen build <options>

Gera a publicação.

O comando irá gerar os arquivos .md na pasta dist da publicação. Os arquivo gerados serão utilizados na conversão pelo comando convert.

options

  • -p, --publication: Nome da publicação que será gerada. Se não passada o comando retorna um erro.
  • -m, --md: Gera somente os arquivos .md da publicação.

version

pnpm pub-gen version <options>

Realiza uma série de perguntas na cli para gerar a versão da publicação. Para mais informações veja a página Versionamento.

options

  • -p, --publication: Nome da publicação que será versionada. Se não passada o comando retorna um erro.

convert

pnpm pub-gen convert <options>

Converte os arquivos da publicação para o formato especificado.

options

  • -p, --publication: Nome da publicação que será convertida. Se não passada o comando retorna um erro.
  • -o, --output: Pasta de destino dos arquivos convertidos. Se não passada será gerada na pasta dist da publicação.
  • -e, --ext: Extensão dos arquivos convertidos. Se não passada será gerado um arquivo .docx por padrão.
  • -t, --title: Título do arquivo convertido. Se não passada será utilizado o título da publicação.

Como contribuir

Instalando o pub-gen

O pub-gen é um pacote do monorepo elucidario. Para instalar o pub-gen no monorepo execute:

pnpm i -w @elucidario/pkg-pub-gen

Para editar o pub-gen modifique os arquivos na pasta packages/pub-gen.

Os comandos a seguir são executados na raiz do pub-gen.

cd packages/pub-gen

Build

Para gerar a build do pub-gen execute:

pnpm build

Neste comando serão gerados os arquivos .md da documentação na pasta docs e os arquivos .json na pasta static.

Testes

Para executar os testes do pub-gen execute:

pnpm test

Cobertura de testes:

File% Stmts% Branch% Funcs% LinesUncovered Line #s
All files96.0570.7610095.94
createInput.js87.583.3310087.528
index.js0000
pubGenPrompt.js88.235010088.2371-74
referencePrompt.js10078.0410010082-183,218-221

todo

  • revisar documentação
  • Criar um preset para o padrão de publicação da APA
  • Estabelecer um meio para que gere arquivos google-docs para diferentes presets.
  • Possibilidade de permitir o uso de pastas ou arquivos com extensão .md para determinar seções do texto na pasta content.