Como usar este template

Este repositório gera o site de entregas da disciplina. O fluxo é sempre o mesmo: você edita um Markdown (ou commita um notebook) dentro de docs/, dá git push na main, e o GitHub Actions publica o site.

Estrutura de pastas

Os nomes abaixo são um contrato com a correção — não os renomeie.

docs/
  index.md                       # capa: grupo e status das entregas
  exercises/
    data/
      index.md                   # o relatório
      code/                      # scripts, como arquivos executáveis
      figures/                   # imagens commitadas
    perceptron/
    mlp/
    vae/
  projects/
    index.md                     # visão geral: equipe, dataset, as 3 entregas
    eda/
      index.md
      code/
      figures/
    classification/              # escolha classification OU regression
    regression/                  # e apague a pasta que sobrar
    generative/
mkdocs.yml
requirements.txt

Cada entrega tem a própria pasta, sempre com o mesmo formato: index.md para o relatório, code/ para os scripts e figures/ para as imagens. Se a entrega for um notebook, ele entra na mesma pasta — data/index.ipynb no lugar de data/index.md.

O projeto é um só: as três entregas de projects/ compartilham equipe e dataset, e a segunda é classificação ou regressão, nunca as duas.

Front matter obrigatório

Todo relatório começa com:

---
exercise: data
ai_use: "descreva o uso de IA, ou 'none'"
---

Nos projetos, troque exercise: por project: (eda, classification, regression, generative). Os dois campos são obrigatórios.

Colocando uma entrega no menu

Um item de menu por entrega, em mkdocs.yml. O alvo pode ser Markdown, notebook .ipynb ou um link do Colab — os três exemplos estão em Exemplos de uso.

Antes de publicar

Todas as linhas do mkdocs.yml que você precisa trocar estão marcadas com # TROCAR:

site_name: ANN-DL · Entregas                  # TROCAR: título exibido no topo do site
site_author: Seu Nome, Sobrenome              # TROCAR: seu nome (ou os nomes do grupo)
site_url: https://usuario.github.io/ann-dl    # TROCAR: https://<seu-usuario>.github.io/<seu-repo>
repo_url: https://github.com/usuario/ann-dl   # TROCAR: https://github.com/<seu-usuario>/<seu-repo>
repo_name: usuario/ann-dl                     # TROCAR: <seu-usuario>/<seu-repo>

Há mais uma no nav, na URL do Colab. Para achar todas:

grep -n "TROCAR" mkdocs.yml

O passo a passo completo está em Publicação no GitHub Pages.

Pré-requisitos

Antes de começar, certifique-se de que você possui os seguintes pré-requisitos instalados em seu sistema:

• Git: Para clonar o repositório.

Instalando o Python

Python 3.10 ou superior. O GitHub Actions constrói o site com a versão definida em PYTHON_VERSION, no workflow — usar localmente a mesma versão evita surpresas entre o seu build e o do CI.

sudo apt install python3 python3-venv python3-pip
python3 --version

brew install python
python3 --version

python --version

Instalando as dependências

Para rodar o site na sua máquina, siga os passos a seguir.

Clone ou fork este repositório:

git clone <URL_DO_REPOSITORIO>

Crie um ambiente virtual do Python:

python3 -m venv env

python -m venv env

Ative o ambiente virtual (você deve fazer isso sempre que for executar algum script deste repositório):

source ./env/bin/activate

.\env\Scripts\activate

Instale as dependências com:

python3 -m pip install -r requirements.txt --upgrade

python -m pip install -r requirements.txt --upgrade

Publicação no GitHub Pages

O site não é publicado a partir da main: o GitHub Actions constrói o HTML e o empurra para uma branch separada, gh-pages, e é ela que o GitHub Pages serve.

flowchart LR
    push["git push<br/>branch main"] --> ci["GitHub Actions<br/>mkdocs gh-deploy --force"]
    ci -->|escreve| gp["branch gh-pages<br/>(HTML gerado)"]
    gp --> pages["GitHub Pages<br/>usuario.github.io/repo"]

Isso significa que você nunca edita a gh-pages à mão — ela é reescrita a cada push.

Os passos 1 a 4 são feitos uma única vez. Depois disso, publicar é dar git push.

Passo 1 — Repositório público e Actions habilitado

Registre o repositório no formulário da disciplina uma vez, no começo do semestre, e o mantenha público: a correção lê o site e o repositório, e o GitHub Pages exige repositório público em contas gratuitas.

Passo 2 — Garantir que o CI possa escrever

O workflow precisa escrever na branch gh-pages, e o token do Actions não tem esse escopo por padrão. O workflow deste template já o pede explicitamente:

permissions:
  contents: write

Esse bloco sobrepõe o padrão do repositório, então normalmente não há nada a fazer aqui. Ele só não basta em dois casos: se você removeu o bloco, ou se uma política do repositório ou da organização impede que o workflow eleve o próprio escopo.

O workflow completo:

name: ci
on:
  push:
  pull_request:
  # Permite disparar o build à mão em Actions > ci > Run workflow, sem precisar
  # de um commit novo.
  workflow_dispatch:

# Environment
env:
  CI: true
  PYTHON_VERSION: 3.12

# O job precisa escrever na branch gh-pages.
# Isto só tem efeito se, em Settings > Actions > General > Workflow permissions,
# a opção "Read and write permissions" estiver marcada.
permissions:
  contents: write

# Jobs to run
jobs:

  # Build and deploy documentation site
  deploy:
    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:

      # Checkout source from GitHub.
      # fetch-depth: 0 traz o histórico completo — sem ele os plugins git-authors e
      # git-revision-date-localized não conseguem datar as páginas.
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Install Python runtime and dependencies
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      # pip
      - run: |
          pip install -r requirements.txt

      # deploy
      - run: |
          mkdocs gh-deploy --force

Passo 3 — Publicar

git add .
git commit -m "exercises/data: relatório do exercício 1"
git push

Acompanhe em Actions. O primeiro run cria a branch gh-pages; leva 1–2 minutos.

Passo 4 — Apontar o Pages para a branch gh-pages

Só depois que o primeiro run terminar (a branch precisa existir): em Settings → Pages, em Build and deployment, escolha Deploy from a branch, selecione a branch gh-pages e a pasta / (root), e salve.

O endereço aparece no topo dessa mesma tela, no formato https://<seu-usuario>.github.io/<seu-repo>/. Ele precisa ser idêntico ao site_url do mkdocs.yml — é dele que o Material monta os links do menu e o sitemap.xml.

Passo 5 — Conferir

• O run em Actions terminou com o check verde.
• A branch gh-pages existe e tem um index.html na raiz.
• A URL de Settings → Pages abre o site.
• O menu tem as suas entregas, e nenhum link quebrado.
• Nada de usuario/ann-dl sobrou: grep -rn "TROCAR\|usuario/ann-dl" mkdocs.yml docs/

Validando antes do push

O CI publica mesmo com avisos; o modo estrito, não. Rode localmente antes de commitar:

mkdocs serve -o                  # preview com recarga automática
mkdocs build --strict            # falha em link quebrado ou snippet inexistente

Publicação manual

Se precisar publicar sem esperar o CI — ou se o Actions estiver indisponível:

mkdocs gh-deploy

O comando constrói o site e empurra para a gh-pages usando as suas credenciais do Git. Ele não substitui o Passo 2: assim que você voltar a dar push na main, quem publica é o CI.

Quando não funcionar