Doc Engine
This release note is written in English and Portuguese, scroll to the end to access both languages.
Esta release note está escrita em Inglês e Português, role a página até o final para ter acesso às duas linguagens.
In addition to creating documentation for plugins and actions, content creators can now document stacks and starters.
What is Doc Engine and its benefits?
From this implementation, content creators documents plugins, actions, sctaks and starters through a single file generated in the content creator's local directory as soon as they give the command to create one of these contents via CLI. For content creators, the evolution of the documentation feature brings benefits in terms of keeping documentation close to the code of the created content. Just as it will no longer be necessary to create a new version of a plugin, action or stack whenever you need to update the documentation, as we have a command in the CLI that makes it possible to update the documentation. Another perceived benefit is the possibility of creating documentation for the stack and starter, where it was not possible before this feature.
How it works?
Create documentation
1 - Enter any of the commands below:
stk create plugin
stk create action
stk create stack
stk create starter
2 - Answer the terminal's questions.
3 - Check the folders /docs/pt_br and /docs/en_us with their respective .md files generated in your local directory:
4 - Edit the generated files as you wish to document.
5 - Enter the publication command for your respective content, which could be:
stk publish plugin --studio <studio-slug>
stk publish action --studio <studio-slug>
stk publish stack --studio <studio-slug>
Ready! Its contents were published together with written documentation.
Note: Files must be written in .md format and will be rendered for display on the stackspot.com portal.
Update documentation
If you need to update your documentation, follow these steps:
1 - Say login to the STK CLI:
stk login
2 - Write the changes you want to make in the .md file;
3 - Run the command below:
stk update doc --studio <studio-slug>
Ready! The changes were signed in the documentation.
Supporting content
Além de criar documentação para plugins e actions, agora os criadores de conteúdo podem documentar stacks e starters.
O que é Doc Engine e seus benefícios?
A partir dessa implementação, criadores de conteúdo documentos para plugins, actions, sctaks e starters através de um único arquivo gerado no diretório local do criador de conteúdo assim que derem o comando para criar um desses conteúdos via CLI. Para os criadores de conteúdo, a evolução do recurso de documentação traz benefícios em termos de manutenção da documentação próxima ao código do conteúdo criado. Assim como não será mais necessário criar uma nova versão de um plugin, action ou stack sempre que precisar atualizar a documentação, pois temos um comando na CLI que possibilita a atualização da documentação. Outro benefício percebido é a possibilidade de criação de documentação para o stack e starter, onde não era possível antes dessa feature.
Como funciona?
Criar documentação
1 - Inserir qualquer um dos comandos abaixo:
stk create plugin
stk create action
stk create stack
stk create starter
2 - Responder as perguntas do terminal.
3 - Confira as pastas /docs/pt_br e /docs/en_us com seus respectivos arquivos .md geradas no seu diretório local:
4 - Edite os arquivos gerados conforme deseja documentar.
5 - Insira o comando de publicação do seu respectivo conteúdo, podendo ser:
stk publish plugin --studio <studio-slug>
stk publish action --studio <studio-slug>
stk publish stack --studio <studio-slug>
Pronto! Seu conteúdo foi publicado juntamente com a documentação escrita.
Observação: os arquivos devem ser escritos no formato .md e serão renderizados para exibição no portal da stackspot.com.
Atualizar documentação
Caso necessite atualizar sua documentação, siga os passos:
1 - Fala login no STK CLI:
stk login
2 - Escreva as mudanças que você quer fazer no arquivo .md;
3 - Execute o comando abaixo:
stk update doc --studio <studio-slug>
Pronto! As mudanças foram subscritas na documentação.