Converter um projeto em Stack

Nesta seção, você encontra um tutorial de como converter o seu projeto existente em uma Stack, dividindo seu projeto em Template e Plugins.

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.

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.

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 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 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 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 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 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.stackspot.com/latest/docs/creators-guide/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.stackspot.com/latest/docs/creators-guide/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 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 arquivo INDEX.md na pasta templates do 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 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!

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.

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 create stackfile docs-stackfile

Passo 4. Editar o arquivo docs-stackfile.yaml para 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 import stack <URL-da-sua-stack>.