Ir para o conteúdo

Configurações para criar posts e atualizar os sites do AutomatizaMG⚓︎

Aqui na equipe Automatiza.MG todo dia é dia de conhecimento!

Nesse post listaremos todas as configurações necessárias para instalar e configurar o Git, o Python, o MkDocs e outras ferramentas úteis para atualizar os sites do AutomatizaMG, bem como criar novos post nos blogs.

Não perca essa oportunidade de contribuir para o crescimento de nossa equipe, seja participando como ouvinte ou como tutor! É a nossa chance de se atualizar, compartilhar conhecimento e aprimorar nossas habilidades! 🚀🚀

Estrutura geral dos repositórios que sustentam os sites estáticos:⚓︎

- .github

 - workflows

- docs

 - assets

 - blog

  - posts

   - .authors.yml

   - index.md

- pasta menu principal

- pasta menu principal

- overrides

- sources

- venv

 - .gitignore

 - abbreviations.md

 - CHANGELOG.md

 - mkdocs.yml

 - README.md

 - requirements.txt

1. Github e Git Bash (CLI)⚓︎

1.1. Fazer conta no Github e confirmar conta no email

1.2. Definir perfil de acesso nos repositórios

1.3. Baixar Git Bash

1.4. Configurar Git Bash

git config --global user.name "andrelamor"
git config --global user.email "andre.amorim@planejamento.mg.gov.br"
git config --list # lista as configuracoes atuais

1.5. Arquivos e diretórios

1.6. Trabalhando com arquivos e repositórios

  • Fluxo de trabalho
  git clone <url> # importar repositório
  git pull # importar últimas mudanças do ORIGIN MAIN 
  git status 
  git add <files> # levar arquivos alterados para STAGING AREA
  git diff # verificar alterações nos arquivos
  git commit -m "<message>"
  git status # estado do repositório
  git log
  git push origin main
  • Inicializar repositório
  git init

2. Instalar e configurar Python⚓︎

Seguir os passos indicados neste post.

Após inserção das pastas do Python no PATH como variável de ambiente (WINDOWS), verificar se o terminal BASH (CLI) também o identifica, como o CMD do Windows: 

$ python --version
Python 3.13.1

3. Instalar e congigurar ferramentas de interface gráfica (GUI)⚓︎

  1. Editor de texto: Sublime Text

  2. Modificar editor de texto padrão, de Vim para Sublime Text

  3. $ git config --global core.editor "'c:/program files/sublime text 3/sublime_text.exe' -w"

  4. Ferramenta GUI para o gihub: Sublime Merge

  5. Verificar se as pastas dos sowtwares acima estão no PATH das variáveis de ambiente

4. Ambiente virtual e gerenciamento de dependências (requirements)⚓︎

Para utilizar ferramentas de site estático, precisamos simular localmente as alterações, antes de enviá-las para o reositório ORIGIN do Github. Para isso, instalamos pacotes usando ambiente virtual do Python, via linha de comnado (Git bash).

Os arquivos requirements.txt exemplo em cada repositório contém essas dependências a serem instaladas.

# grep para filtrar resultado de uma busca
$ ls -la | grep handbook

# criação ambiente virtual python - apenas uma vez por repositório
# windowns, linux e emac
$ python -m venv venv

# ativação ambiente nowindows
$ source venv/Scripts/activate
# ativação ambiente nolinux e mac
$ source venv/bin/activate

# instalação pacotes - apenas uma vez, ou sempre que novo
# pacote for acrescentado no arquivo requirements.txt
$ pip install -r requirements.txt

# veririfcar pacotes instalados
$ pip list

# desativar o ambiente (venv)
$ deactivate

  • Pontos importantes

  • conferir a marcação entre parêntesis (venv)

  • navegar pelas pastas e verificar pip list com e sem o ambiente virtual

- Referências:

5. Criar e editar posts no blog e novas seções nos sites (Mkdocs)⚓︎

Após instalar os pacotes necessários, o próximo passo, após ativar o servidor local (venv) é projetar o site localmente através do pacote MKDocs:

# ativação ambiente no windows
$ source venv/Scripts/activate
# ativação ambiente no linux e mac
$ source venv/bin/activate

# ligar servidor local mkdocs
$ mkdocs serve

# construir documentação (quando arquivo novo for adicionado no mkdocs.yml)
$ mkdocs build

Caso haja algum conteúdo novo em aba do site que não seja a do Blog, será necessário adicionar a respectiva referência no arquivo mkdocs.yml, e construir a documentação no MKDocs, antes de projetá-la localmente:

# construir documentação (quando arquivo novo for adicionado no mkdocs.yml)
$ mkdocs build

- Referências:

6. Criar e editar fluxogramas (Mermaid)⚓︎

  • O fluxo ilustrando a sequência de ações no github:
    graph TD; 1((Início))-->2; 2{git iniciado no projeto?} 2 --> |não| 3[git init] 3 --> 11[Cria repositório Github] 11 --> 12[git remote add <nome_remote> <endereço_remote>] 12 --> 4 2 --> |sim| 4[git status] 4 --> 5{Commitar na branch main?} 5 --> |sim| 6[git add <file_name>] 6 --> 7[git commit -m <commit_message_entre_aspas>] 7 --> 5 5 --> |não| 8{Criar nova branch?} 8 --> |sim| 9[git pull origin main] 8 --> |não| 16((Fim)) 9 --> 10[git checkout -b <nova_branch_nome>] 10 --> 13{Commitar?} 13 --> |sim| 14[git add <file_name>] 14 --> 15[git commit -m <commit_message_entre_aspas>] 13 --> |não| 17{Abrir PR Github?} 15 --> 13 17 --> |sim| 18[git push <nome_remote> <nova_branch_nome>] 17 --> |não| 16 18 --> 20[Abrir/aprovar PR Github] 20 --> 21[git checkout main] 21 --> 22[git pull origin main] 22 --> 23{Deletar <nova_branch_nome> já mergiada?} 23 --> |sim| 24[git branch -d <nova_branch_nome>] 23 --> |não| 5 24 --> 5

- Referências:

Referências Gerais⚓︎

- Documentação Material Mkdocs⚓︎

Comentários