Atualiza manual

.github/workflows/deploy.yml

@@ -0,0 +1,52 @@
+name: Deploy
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - name: Build
+        run: |
+          uv sync --frozen
+          uv run mkdocs build --strict
+
+      - name: Publicar em gh-pages (raiz)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          REPO_URL="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          if git ls-remote --exit-code --heads origin gh-pages; then
+            git clone --depth 1 --branch gh-pages "$REPO_URL" gh-pages
+          else
+            mkdir gh-pages
+            git -C gh-pages init -b gh-pages
+          fi
+          # apaga conteúdo antigo da raiz, preservando os diretórios de preview (pr-*)
+          rsync -a --delete --exclude '/pr-*' --exclude '.git' site/ gh-pages/
+          cd gh-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if git diff --cached --quiet; then
+            echo "Nenhuma mudança para publicar."
+          else
+            git commit -m "Deploy de ${GITHUB_SHA::7}"
+            git push "$REPO_URL" HEAD:gh-pages
+          fi

.github/workflows/preview.yml

@@ -0,0 +1,128 @@
+name: Preview de PR
+
+# Dois triggers de propósito:
+# - pull_request: roda o workflow da branch da PR; usado para PRs do MESMO
+#   repositório (token com escrita). É o que permite preview em PRs que ainda
+#   não têm este arquivo na master.
+# - pull_request_target: roda o workflow da master; usado para PRs de FORKS
+#   (o token de pull_request em fork é somente-leitura e não conseguiria
+#   publicar o preview).
+# As condições nos jobs garantem que apenas um dos dois executa por evento.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+  pull_request_target:
+    types: [opened, synchronize, reopened, closed]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: pr-preview-${{ github.event_name }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+env:
+  PR: ${{ github.event.pull_request.number }}
+  PREVIEW_URL: https://manual.pythonbrasil.org.br/pr-${{ github.event.pull_request.number }}/
+
+jobs:
+  publicar:
+    if: >
+      github.event.action != 'closed' && (
+        (github.event_name == 'pull_request' &&
+         github.event.pull_request.head.repo.full_name == github.repository) ||
+        (github.event_name == 'pull_request_target' &&
+         github.event.pull_request.head.repo.full_name != github.repository)
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - name: Build
+        env:
+          SITE_URL: ${{ env.PREVIEW_URL }}
+        run: |
+          uv sync --frozen
+          uv run mkdocs build
+
+      - name: Publicar em gh-pages/pr-$PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          REPO_URL="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          if git ls-remote --exit-code --heads origin gh-pages; then
+            git clone --depth 1 --branch gh-pages "$REPO_URL" gh-pages
+          else
+            mkdir gh-pages
+            git -C gh-pages init -b gh-pages
+          fi
+          rsync -a --delete site/ "gh-pages/pr-${PR}/"
+          cd gh-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if git diff --cached --quiet; then
+            echo "Nenhuma mudança no preview."
+          else
+            git commit -m "Preview da PR #${PR}"
+            git push "$REPO_URL" HEAD:gh-pages
+          fi
+
+      - name: Comentar na PR com o link do preview
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const marker = "Preview da documentação";
+            const body = [
+              `📖 **${marker}**: ${process.env.PREVIEW_URL}`,
+              ``,
+              `Atualizado a cada push nesta PR (commit ${context.sha.substring(0, 7)}).`,
+            ].join("\n");
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request.number;
+            const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number });
+            const existing = comments.find((c) => c.body?.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+            }
+
+  limpar:
+    if: >
+      github.event.action == 'closed' && (
+        (github.event_name == 'pull_request' &&
+         github.event.pull_request.head.repo.full_name == github.repository) ||
+        (github.event_name == 'pull_request_target' &&
+         github.event.pull_request.head.repo.full_name != github.repository)
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Remover preview de gh-pages/pr-$PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          git ls-remote --exit-code --heads origin gh-pages || exit 0
+          REPO_URL="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          git clone --depth 1 --branch gh-pages "$REPO_URL" gh-pages
+          cd gh-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git rm -r --ignore-unmatch "pr-${PR}"
+          if git diff --cached --quiet; then
+            echo "Nada para remover."
+          else
+            git commit -m "Remove preview da PR #${PR}"
+            git push "$REPO_URL" HEAD:gh-pages
+          fi

.gitignore

@@ -1 +1 @@
-build/
+site/

.python-version

@@ -0,0 +1 @@
+3.13

.readthedocs.yaml

@@ -1,10 +1,14 @@
 version: 2
+
 build:
-  os: "ubuntu-20.04"
+  os: "ubuntu-24.04"
   tools:
-    python: "3.10"
+    python: "3.13"
   jobs:
+    post_create_environment:
+      - pip install uv
     post_install:
-      - pip install poetry
-      - poetry export --format requirements.txt --without-hashes > requirements.txt
-      - pip install -r requirements.txt
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen
+
+mkdocs:
+  configuration: mkdocs.yml

Makefile

@@ -1,26 +1,18 @@
-# Minimal makefile for Sphinx documentation
+# Minimal makefile for MkDocs documentation
 #
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+MKDOCS ?= uv run mkdocs
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Uso:"
+	@echo "  make live    - servidor local com recarga automática (http://localhost:8000)"
+	@echo "  make deploy  - gera o site estático em ./site"
 
-.PHONY: help Makefile
+.PHONY: help live deploy
 
 live:
-	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(MKDOCS) serve --dev-addr 0.0.0.0:8000
 
 deploy:
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for$(SPHINXOPTS).
-%: Makefile
-	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(MKDOCS) build

README.md

@@ -10,10 +10,9 @@ O manual está disponível online em [manual.pythonbrasil.org.br](https://manual
 
 ### Tecnologias utilizadas
 - Python
-- [Sphinx](http://sphinx.pocoo.org)
-- Myst-parser
-- [Poetry](https://python-poetry.org/docs/)
-  > Caso você utilize uma distribuição Linux, talvez você precise tratar um erro conhecido seguindo [essa orientação](https://github.com/python-poetry/poetry/issues/5241#issuecomment-1063513340).
+- [MkDocs](https://www.mkdocs.org/)
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+- [uv](https://docs.astral.sh/uv/)
 
 ### Instalação
 
@@ -28,15 +27,15 @@ O manual está disponível online em [manual.pythonbrasil.org.br](https://manual
    ```
 4. Instale as dependencias:
    ```
-   poetry install
+   uv sync
    ```
 5. Gere a documentação:
    ```
-   poetry run make live
+   make live
    ```
 
 ### Visualize o manual
 1. No seu navegador, abra o link http://localhost:8000.
 
 ### Atualização e Complementação de conteúdo
-A cada nova Python Brasil este manual deve ser atualizado pela organização da PyBR com as informações referentes ao evento, seguindo as instruções do [Guia de Atualização do Manual](/CONTRIBUTING.md).
+A cada nova Python Brasil este manual deve ser atualizado pela organização da PyBR com as informações referentes ao evento, seguindo as instruções do [Guia de Atualização do Manual](/docs/CONTRIBUTING.md).

docs/CNAME

@@ -0,0 +1 @@
+manual.pythonbrasil.org.br

docs/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Guia de Atualização do Manual
+
+Este guia orienta sobre a inserção de novos conteúdos no Manual da Big Kahuna do ponto de vista de padronização de dados e informações, bem como da formatação utilizada para o conteúdo.
+
+**Sumário**
+
+## Inserindo dados da Python Brasil
+Para inserir os dados do evento que você acaba de realizar, você deve criar um arquivo dentro da pasta `docs/historia` com as seguintes características:
+
+- Formato: Markdown;
+- Título: `pythonbrasil[número da edição]`
+- Conteúdo:
+
+```
+# Python Brasil [ANO DE REALIZAÇÃO DO EVENTO]
+
+[Em construção ...]
+```
+
+Em seguida, registre a nova página nos dois lugares onde a navegação é montada:
+
+1. No `mkdocs.yml` (raiz do repositório), dentro da seção `História da Python Brasil` do `nav`:
+
+   ```yaml
+   - Python Brasil [ANO]: historia/pythonbrasil[número da edição].md
+   ```
+
+2. Na lista em `docs/historia/index.md`, mantendo a ordem cronológica:
+
+   ```markdown
+   * [Python Brasil [ANO]](pythonbrasil[número da edição].md)
+   ```
+
+## Trechos reutilizáveis de orientações
+
+Dicas que se aplicam a mais de uma escala de evento ficam centralizadas em
+`docs/orientacoes-gerais.md` (arquivo não publicado no site). Para adicionar ou
+alterar uma dica geral, edite a seção correspondente nesse arquivo; as páginas
+`orientacoes.md` dos eventos regionais e da Python Brasil incluem os trechos
+via snippets e são atualizadas automaticamente. Veja as instruções no próprio
+arquivo central.

docs/escalas/index.md

@@ -0,0 +1,72 @@
+# Escalas de Eventos Python
+
+Nem toda comunidade começa organizando uma Python Brasil. Existem diferentes escalas de eventos, cada uma com seus desafios e aprendizados. Este guia vai te ajudar a identificar em qual estágio sua comunidade está e qual caminho seguir.
+
+## Checklist: Qual o próximo passo da sua comunidade?
+
+Responda as perguntas abaixo para descobrir qual guia é mais adequado para o momento da sua comunidade:
+
+### 1. Sua comunidade já realiza encontros presenciais ou online regularmente?
+
+- [ ] **Não, estamos começando do zero** --> Siga para o [guia de meetups](meetups/index.md)
+- [ ] **Sim, fazemos meetups mensais ou bimestrais** --> Siga para a pergunta 2
+
+### 2. Quantas pessoas participam dos seus encontros regularmente?
+
+- [ ] **Menos de 30 pessoas** --> Continue fortalecendo os meetups - [guia de meetups](meetups/index.md)
+- [ ] **Entre 30 e 100 pessoas** --> Siga para a pergunta 3
+- [ ] **Mais de 100 pessoas** --> Considere um evento regional - [guia de eventos regionais](regionais/index.md)
+
+### 3. Sua comunidade já organizou algum evento com mais de 100 participantes?
+
+- [ ] **Não, mas queremos tentar** --> Siga para o [guia de eventos regionais](regionais/index.md)
+- [ ] **Sim, e queremos crescer mais** --> Considere candidatar-se para uma [Python Brasil](nacional/index.md)
+
+### 4. Sua comunidade abrange apenas uma cidade ou já tem alcance regional?
+
+- [ ] **Apenas uma cidade** --> Fortaleça os meetups e conexões regionais - [guia de meetups](meetups/index.md)
+- [ ] **Já temos pessoas de várias cidades do estado/região** --> [guia de eventos regionais](regionais/index.md)
+
+---
+
+## Visão Geral das Escalas
+
+| Característica | Meetup | Evento Regional | Python Brasil |
+|----------------|--------|-----------------|---------------|
+| **Público esperado** | 20-100 pessoas | 100-500 pessoas | 500-1500 pessoas |
+| **Duração** | 2-4 horas | 2-4 dias | 4-6 dias |
+| **Equipe necessária** | 2-5 pessoas | 5-10 pessoas | 20-30 pessoas |
+| **Frequência** | Mensal/Bimestral | Anual | Anual |
+| **Orçamento típico** | R$ 0-500 | R$ 50.000-100.000 | R$ 200.000-500.000+ |
+| **Patrocínios** | Opcionais, locais | Necessários, regionais e nacionais | Essenciais, nacionais e internacionais |
+
+---
+
+## Progressão Natural
+
+A maioria das comunidades segue uma progressão natural:
+
+```
+Meetups regulares
+      |
+      v
+Evento de 1 dia (workshops + talks)
+      |
+      v
+Evento regional (2-3 dias, múltiplas trilhas)
+      |
+      v
+Python Brasil (evento nacional)
+```
+
+**Não tenha pressa.** Cada etapa tem seu valor e seus aprendizados. Uma comunidade que faz meetups consistentes e de qualidade é mais valiosa do que uma que tenta eventos grandes sem base.
+
+---
+
+## Guias Disponíveis
+
+Cada guia é dividido em tópicos de acordo com o escopo do evento, como **Processo e Governança**, **Times e Organização**, **Orientações Gerais**, **Financeiro e Patrocínio** e **Marketing e Divulgação**. Alguns guias têm tópicos adicionais: os eventos regionais contam com **Ferramentas**, e a Python Brasil com **Proposta de Candidatura**. Os meetups, por serem menores, não possuem página de orientações.
+
+* [Guia de Meetups Python](meetups/index.md)
+* [Guia de Eventos Regionais Python](regionais/index.md)
+* [Organizando uma Python Brasil](nacional/index.md)