@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 Brasilapa
- 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 arquivopub-gen-config.json
mesmo que ele já exista.-d, --default
: Cria o arquivopub-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 pastareferences
do monorepo.
search
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 pastareferences
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 pastadist
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 | % Lines | Uncovered Line #s |
---|---|---|---|---|---|
All files | 96.05 | 70.76 | 100 | 95.94 | |
createInput.js | 87.5 | 83.33 | 100 | 87.5 | 28 |
index.js | 0 | 0 | 0 | 0 | |
pubGenPrompt.js | 88.23 | 50 | 100 | 88.23 | 71-74 |
referencePrompt.js | 100 | 78.04 | 100 | 100 | 82-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 pastacontent
.