1. Primeiros Passos

Este guia tem como objetivo apresentar o processo e as ferramentas necessárias para colaborar na escrita e manutenção da documentação do projeto.

1.1 Ferramentas e Configuração do Ambiente

Para garantir a visualização correta da documentação durante o desenvolvimento e a geração final dos arquivos, é essencial configurar o ambiente de trabalho e instalar o MkDocs.

1.1.1. Configuração do Ambiente Virtual (Windows)

Recomenda-se o uso de um ambiente virtual para isolar as dependências do projeto. Siga os passos abaixo para configurá-lo no Windows:

• Abra o Prompt de Comando ou PowerShell na pasta raiz do repositório do projeto.

• Crie o ambiente virtual (geralmente nomeado como venv):

python -m venv venv

• Ative o ambiente virtual:

.\venv\Scripts\activate

Se estiver usando o PowerShell e tiver problemas de permissão, pode ser necessário executar o comando Set-ExecutionPolicy RemoteSigned -Scope Process e tentar a ativação novamente.

• Instale o MkDocs:

pip install mkdocs

Se houver extensões adicionais no projeto, elas deverão ser instaladas seguindo instruções específicas (ex: pip install mkdocs-material).

O ambiente virtual estará ativo quando você vir (.venv) no início da linha de comando. Para desativá-lo, basta digitar deactivate.

1.1.2. Configuração do .gitignore

Para evitar que arquivos temporários e do ambiente virtual sejam rastreados pelo Git e incluídos nos commits, crie ou atualize o arquivo .gitignore na raiz do repositório com o seguinte conteúdo:

# Python Virtual Environment
.venv/
venv/
*.pyc

# IDE Configuration
.vscode/

# QGIS files (temporarily generated)
*.qgs~
*.qgz~

# Documentation/build artifacts (as per project documentation)
_build/
_output/

1.1.3. Visualizando a Documentação Localmente

Com o MkDocs instalado no ambiente virtual, você pode visualizar as alterações em tempo real (servidor local):

• Certifique-se de que o ambiente virtual (venv) está ativo.
• Execute o comando na raiz do repositório:

mkdocs serve

• Abra seu navegador e acesse o endereço fornecido (geralmente http://127.0.0.1:8000/).

1.2. Estrutura e Organização dos Arquivos

A documentação é escrita em Markdown e segue uma estrutura de diretórios e arquivos bem definida para a organização dos conteúdos.

1.2.1. Hierarquia de Arquivos

• O diretório principal da documentação é docs/.
• O arquivo principal é docs/index.md, que contém o conteúdo da página inicial.
• Os subdiretórios dentro de docs/ representam as "seções" da documentação (ex: docs/guia-usuario/).
• Cada arquivo Markdown dentro de uma seção representa um "capítulo". Não há subdiretórios dentro das pastas de seção.

1.2.2. Nomenclatura e Numeração de Capítulos

A numeração explícita é fundamental para a organização e o ordenamento do menu de navegação:

A ferramenta MkDocs se encarrega de organizar os subcapítulos no menu lateral, bastando a numeração correta dentro do arquivo Markdown. A numeração no nome do arquivo (1_...md) não é obrigatória, mas serve como apoio para a configuração do menu de navegação.

1.3. Arquivo de configurações da documentação (mkdocs.yml)

Sempre que um novo capítulo for criado, o menu de navegação precisa ser atualizado manualmente no arquivo de configuração principal: mkdocs.yml (localizado na raiz do repositório).Isto não é necessariamente obrigatório para que o menu seja construído pelo mkdocs, mas este recurso possibilita definição personalizada de navegação.

1.3.1. Alterando o Marcador nav

Você deve focar apenas no marcador nav. A estrutura é definida por identação (espaços).

• Seções/Subseções: Apenas possuem um título e um nível de identação. Não possuem especificação de arquivo.
• Capítulos: Devem ser identados abaixo de sua respectiva Seção/Subseção e devem ter a referência ao arquivo Markdown.

Exemplo de Estrutura:

Se você criar um novo capítulo 2_exemplo.md dentro da seção docs/contribuicao/, você deve editar o mkdocs.yml da seguinte forma:

# Conteúdo acima não precisa ser alterado
# ...

nav:
    - Início: index.md
    - Introdução:
        - Visão Geral: introducao/1_visao_geral.md
        - Primeiros Passos: introducao/2_primeiros_passos.md
    - Contribuição (Seção Exemplo):
        - 1. Estrutura: contribuicao/1_estrutura.md
        - 2. Guia de Estilos (NOVO): contribuicao/2_exemplo.md # Novo capítulo adicionado
    - Referência:
        - API: referencia/api.md
        - Glossário: referencia/glossario.md

# ...
# Conteúdo abaixo não precisa ser alterado

Atenção: A numeração do capítulo no título (2. Guia de Estilos) deve coincidir com o número no nome do arquivo (2_guia_de_estilos.md) e a posição na lista.

1.4. Caixas de Alerta

Ao escrever o conteúdo, utilize a sintaxe Markdown padrão. Para informações de destaque ou avisos importantes, o MkDocs oferece suporte a Caixas de Alerta (também chamadas de Admonitions).

• Recomenda-se a utilização dessas caixas para:
  • Notas (Note) informativas.
  • Dicas (Tip) ou boas práticas.
  • Avisos (Warning) sobre possíveis problemas.
  • Perigo (Danger) alerta de perigo extremo.

Escolha o tipo de caixa com atenção para que a mensagem e a cor transmitam a messagem correta ao leitor.

Próximos Passos: Com este guia, você já pode começar a estruturar seu ambiente de trabalho e colaborar na escrita de documentos.