Apêndice B — Como adicionar capítulos

Este apêndice é o guia de trabalho para os autores (especialmente para o Érico) irem adicionando capítulos conforme a pesquisa avança — deixando todo o histórico no Git.

B.1 O que você precisa ter instalado

  • Git (e uma conta com acesso ao repositório);
  • Quarto (o RStudio recente já vem com Quarto);
  • R com o pacote terra (para os capítulos com mapas): install.packages("terra").

B.2 Editando pelo RStudio (recomendado)

O repositório inclui o arquivo tutorial-trigrs.Rproj — dê dois cliques nele (ou File → Open Project no RStudio) e todo o projeto abre no RStudio:

  1. Os capítulos .qmd aparecem no painel Files — abra, edite (o editor Visual do RStudio permite editar como se fosse um documento Word) e salve;
  2. Botão Render (ou Build → Render Book) para ver o resultado no navegador;
  3. Aba Git do RStudio para Commit (marque os arquivos → mensagem → Commit) e Push — sem precisar de linha de comando;
  4. Em 1–2 minutos o site público está atualizado.

B.3 Fluxo de trabalho (linha de comando)

# 1. Clonar (só na primeira vez)
git clone https://github.com/sedec-dpm-cgnat/tutorial-trigrs.git
cd tutorial-trigrs

# 2. Antes de começar a trabalhar, sempre atualizar
git pull

# 3. Criar/editar um capítulo: por ex. 06-bacia-hsl.qmd
#    (usar um capítulo existente como modelo)

# 4. Registrar o novo capítulo no _quarto.yml (lista "chapters:")

# 5. Renderizar e conferir localmente (abre o site no navegador)
quarto preview

# 6. Renderizar a versão final (gera o site na pasta docs/)
quarto render

# 7. Versionar e publicar
git add -A
git commit -m "Adiciona capítulo: preparação das grades da bacia HSL"
git push

Ao dar git push, o GitHub Pages publica automaticamente o conteúdo da pasta docs/ — em 1–2 minutos o site está atualizado.

NotaA edição em inglês

As fontes em inglês ficam na pasta en/, com o seu próprio en/_quarto.yml (capítulos novos devem ser registrados também lá, com o mesmo nome de arquivo). O render completo do livro em português apaga a pasta docs/ inteira, inclusive o site em inglês (docs/en/); por isso o gancho _render-en.R (declarado no _quarto.yml da raiz) renderiza a edição em inglês logo em seguida. Para renderizar só a edição em inglês: cd en e quarto render. Antes do commit, confira se docs/en/ está presente. Figuras dos estudos de caso ficam em figuras/<caso>/ na raiz (copiadas inteiras para docs/figuras/); nos capítulos em inglês, use ../figuras/<caso>/....

B.4 Boas práticas

  • Um capítulo por etapa vencida (ex.: preparação do MDE, calibração, análise de sensibilidade). Capítulos curtos e frequentes valem mais que um capítulo gigante no final.
  • Commits pequenos com mensagens descritivas — eles são o “caderno de laboratório” da pesquisa.
  • Erros e becos sem saída também merecem registro (uma seção “o que não funcionou” vale ouro para quem vier depois — e para a dissertação).
  • Dados pesados (MDEs, shapefiles grandes) não entram no Git — ficam na pasta de rede/OneDrive do projeto; o capítulo documenta a origem e o pré-processamento.
  • Figuras geradas por código (R/QGIS) são preferíveis a prints de tela — são reproduzíveis.

B.5 Estrutura de um capítulo típico

# Título do capítulo

Contexto: o que esta etapa faz e por quê.

## Dados usados
Origem, resolução, CRS...

## Procedimento
Passo a passo (comandos, parâmetros escolhidos e justificativa).

```{r}
# código R que gera figuras/tabelas a partir dos resultados
```

## Resultados e interpretação

## Problemas encontrados e soluções