Pular para o conteúdo principal
Version: v4.5.0

Converter um projeto em Stack

Contexto​

Neste tutorial, você verá um projeto preexistente para exemplificar os principais conceitos na conversão do seu projeto pronto em uma Stack.

O projeto de exemplo possui a seguinte estrutura:

DOCUMENTATION
  |__ INDEX.md
  |__ topic1
       |__ doc1.md
       |__ doc2.md
  |__ topic2
       |__ doc1.md
       |__ doc2.md

Neste exemplo você pode ver uma pasta de documentação com:

  • Um index que contém uma referência para as documentações em cada tópico.
  • Uma estrutura de pastas onde cada tópico da documentação é separado por uma nova pasta contendo documentações.

Separar o projeto em Template e Plugins

Analisando a estrutura do projeto de exemplo, é possível definir o que será o Template base do projeto, e os Plugins que serão aplicados na aplicação criada utilizando o Template base.

info

Antes de você começar​

1. O que é um Template?
É o esqueleto de uma Stack que contém o mínimo para torná-la uma aplicação. É um modelo de aplicação que você aplica para construir um projeto.

Neste projeto de exemplo a “estrutura básica” para o Template é:

DOCUMENTATION
  |__ INDEX.md

Essa estrutura contém o básico para manter a documentação:

  1. Uma pasta com o nome do projeto;
  2. Um arquivo INDEX.md que contém as referências para os arquivos da documentação. Agora o template está definido.
info
2. O que é um Plugin?
Extensões de uma Stack que permitem colocar novas capacidades ao Template base por meio da inclusão de código fonte, importação de bibliotecas e até mesmo a execução de comandos e operações complexas para adicionar capacidades a Stack.

Neste projeto de exemplo, a extensão do Template básico são:

  • As novas pastas e os novos documentos que podem ser adicionados à documentação;
  • A inclusão da referência do novo documento no INDEX.md. Este Plugin é responsável por adicionar novos tópicos, seus respectivos arquivos e atualizar o INDEX.md.

Depois de aplicar o Plugin a estrutura do projeto deve ser:

DOCUMENTATION
  |__ INDEX.md
  |__ topic1
       |__ doc1.md
       |__ doc2.md

Criar a Stack base e o Template​

Pré-Requisitos​

  • STK CLI instalado;
  • Criar uma pasta para criar a sua a Stack.
    • Neste tutorial, a pasta será ~/demo.

Passo 1. Navegar até a pasta onde pretende criar a Stack​

cd ~/demo

Passo 2. Criar sua Stack que vai conter seus Plugins e Template​

stk-legacy create stack docs-stack

Sua Stack será criada na pasta atual.

Passo 3. Criar seu Template usando o STK CLI​

Navegue até a pasta da stack criada no passo anterior:

cd ~/demo/docs-stack

Crie seu template dentro da Stack:

stk-legacy create template docs-template

Informe a descrição do Template:

? Template description: Template básico para o projeto de documentações

Seu Template será criado:

template docs-template successfully created!

Passo 4. Editar o Template criado para incluir a estrutura básica que foi definida​

Navegue até a pasta onde o Template foi criado:

~/demo/docs-stack/docs-template

Dentro da pasta há uma pasta templates e um arquivo template.yaml: Estrutura de docs-template:

docs-template
   |_template.yaml
   |_templates

Dentro da pasta templates, se inclui os arquivos que farão parte do Template base. Dentro da pasta templates, você precisa incluir os arquivos para fazer parte do Template base.

Passo 5. Copiar os arquivos base do projeto para a pasta templates do docs-template​

docs-template
   |_template.yaml
   |_templates
         |_INDEX.md

É preciso criar um arquivo INDEX.md vazio dentro da pasta templates do docs-template.

Passo 6. Testar o Template que você criou, criando uma aplicação através do comando stk-legacy create app, usando a flag -p para usar o caminho local do Template​

Volte para a pasta ~/demo:

cd ~/demo

Crie uma aplicação usando o Template local. Para isso, a aplicação deve ser criada fora da Stack:

stk-legacy create app documentation -p ~/demo/docs-stack/docs-template

Sua aplicação será criada na pasta demo com o nome de documentation.

Analise a estrutura da aplicação que você criou, observa-se que o arquivo INDEX.md foi criado corretamente:

documentantion
   |_INDEX.md
   |_stk.yaml //Arquivo de controle do app
   |_.gitignore

Pronto, sua aplicação foi criada a partir de uma estrutura básica de um Template.

Criar os Plugins da Stack​

Depois que o Template base foi definido e criado na sua Stack, você pode criar os Plugins para adicionar as novas capacidades para a sua aplicação.

Contexto​

Este Plugin adiciona uma pasta ao projeto de documentações com o nome recebido por input, e deve adicionar novos arquivos dentro desta pasta criada. Além disso, o Plugin deve editar o arquivo existente de INDEX.md para adicionar a referência ao arquivo criado.

Passo 1. Navegar até a pasta da Stack​

cd ~/demo/docs-stack

Passo 2. Criar a estrutura do plugin através do STK CLI​

stk-legacy create plugin add-docs-plugin

Adicione a descrição do seu plugin:

? Plugin description: Plugin que adiciona novos arquivos e pastas a documentação. Também atualiza o index.

Analise a estrutura do Plugin criado, precisa estar dessa forma:

 add-docs-plugin
    |_docs //pasta para documentação do plugin
    |_templates //Onde ficarão os arquivos do plugin
    |_plugin.yaml //Arquivo de configuração do plugin
    |_plugin.png //Imagem que será exibida no portal
    |_.gitignore

Passo 3. Editar o arquivo plugin.yaml para adicionar os inputs referentes ao nome da pasta a ser adicionada, e o nome do arquivo​

Você pode remover os inputs de exemplo do plugin.yaml e adicionar dois novos:

 - label: Name of documents folder
   type: text
   name: folder_name
   required: true
 - label: Name of document file
   type: text
   name: file_name
   required: true

O arquivo final ficará da seguinte forma:

name: add-docs-plugin
description: Plugin que adiciona novos arquivos e pastas a documentação. Também atualiza o index.
display-name: add-docs-plugin
picture: plugin.png
category: backend # Ref: https://docs.legacy.stackspot.com/latest/docs/create-stacks/yaml/#category
compatibility:
 - java
 - spring
about: docs/about.md
usage: docs/usage.md
use-case: docs/use-case.md
implementation: docs/implementation.md
technologies: # Ref: https://docs.legacy.stackspot.com/latest/docs/create-stacks/yaml/#technologies
 - "Api"
types:
 - app
inputs:
 - label: Name of doc folder
   type: text
   name: folder_name
   required: true
 - label: Name of document file
   type: text
   name: file_name
   required: true

Passo 4. Adicionar a estrutura de pastas da documentação, que será criada quando você aplicar o Plugin​

Dentro da pasta templates do Plugin add-docs-plugin, adicione uma pasta chamada {{folder_name}}:

 add-docs-plugin
    |_templates 
  |_{{folder_name}}

Adicione o arquivo {{file_name}}.md na pasta {{folder_name}}:

 add-docs-plugin
   |_templates 
  |_{{folder_name}}
   |_ {{file_name}}.md

Edite o arquivo {{file_name}}.md, criado anteriormente, para conter em seu cabeçalho o nome do arquivo:

### {{file_name}}

Com estas alterações ao aplicar um Plugin com o comando stk-legacy apply plugin, uma nova pasta será criada com o nome informado no input “folder_name”. E um novo arquivo .md será criado dentro desta pasta com o nome informado no input “file_name”. O arquivo criado já terá em seu título o valor de “file_name”.

Passo 5. Adicionar um arquivoINDEX.mdna pastatemplatesdo Plugin e modificá-lo para incluir a referência aos arquivos adicionados pelo Plugin​

Adicionar o arquivo INDEX.md na raiz da pasta templates do plugin.

add-docs-plugin
|_templates 
 |_INDEX.md
 |_{{folder_name}}
    |_{{file_name}}.md

Ao aplicar este Plugin, o conteúdo do arquivo INDEX.md será mergeado com o conteúdo do INDEX.md original.

Modifique o arquivo INDEX.md do Plugin criado no passo anterior, para incluir a referência aos arquivos adicionados. Copie e cole o conteúdo abaixo em seu arquivo INDEX.md do Plugin, não é necessário alterar nenhum valor.

INDEX.md do plugin:

<br/>[{{file_name}}](/{{folder_name}}/{{file_name}})<br/>

Em aplicações subsequentes do Plugin, o conteúdo do arquivo INDEX.md será mergeado.

Com estas modificações o Plugin está pronto. E agora você pode testá-lo.

Aplicar o Plugin na sua aplicação​

Com o Plugin pronto, podemos aplicá-lo na aplicação que você criou anteriormente.

Passo 1. Navegar até a pasta da aplicação:

cd ~/demo/documentation

Passo 2. Usar o STK CLI para aplicar o Plugin criado em sua Stack usando a flag -p e utilizando o caminho absoluto até a pasta de seu Plugin.

stk-legacy apply plugin -p ~/demo/docs-stack/add-docs-plugin

Insira o nome da pasta:

 ? Name of documents folder: topic1

Insira o nome do arquivo:

 ? Name of document file: doc1.

O Plugin será aplicado.

Passo 3. Analisar a estrutura da aplicação criada.

Observe que o arquivo INDEX.md foi atualizado com a referência ao arquivo adicionado:

INDEX.md da aplicação:

<br/>[doc01](/topic1/doc01)<br/>

A estrutura da aplicação ficará como mostrado abaixo:

documentation
  |__ INDEX.md
   |__ topic1
         |__ doc1.md

O arquivo doc1.md terá o seguinte conteudo:

### doc1

Você aplicou o Plugin!

info

É possível aplicar o mesmo Plugin várias vezes na mesma aplicação, desta forma você pode criar várias pastas/arquivos com um padrão predefinido e adicionar esta informação no INDEX.md.

Criar um Stackfile​

Depois que você criou seu Template e o seu Plugin, você pode criar um Stackfile que facilita o uso do Template e do Plugin em conjunto.

info

O que é um Stackfile? São bundles, ou seja, um conjunto de Templates e Plugins predefinidos de uma Stack que serão aplicados no comando stk-legacy create app.

Passo 1. Acessar a pasta de sua Stack​

cd ~/demo/docs-stack

Passo 2. Acessar a pasta stackfiles​

cd stackfiles

Passo 3. Criar o seu stackfile através do comando​

stk-legacy create stackfile docs-stackfile

Passo 4. Editar o arquivodocs-stackfile.yamlpara incluir os dados de seu Template e Plugin​

O Stackfile ficará da seguinte forma:

type: app
description: "Cria estrutura básica de uma pasta de documentações"
template: docs-stack/docs-template
plugins:
- plugin: docs-stack/add-docs-plugin
 inputs:
   folder_name: use_case
   file_name: use_case

Neste Stackfile, o Template base será utilizado e uma pasta chamada use_case será criada junto a um arquivo use_case.md. Sua Stack pode conter vários Stackfiles, com diferentes inputs.

Subir sua Stack para um repositório GitHub​

Com sua Stack, Template, Plugin e Stackfile criados. Você pode enviar a sua Stack para o GitHub para que ela possa ser usada por outras pessoas.

1. Para subir sua Stack para o GitHub, acesse o diretório da Stack:

cd ~/demo/docs-stack

2. Definir seu repositório como remote da Stack:

git remote add origin <url-do-seu-repositório>

3. Adicionar os arquivos e fazer o commit:

git add --all
git commit --message <mensagem-commit>

4. Enviar a sua Stack:

git push

Agora a sua Stack pode ser usada por meio do comando stk-legacy import stack <URL-da-sua-stack>.

Esta página foi útil?