pep257-exemplo

Projeto didático para estudo de docstrings no padrão PEP 257 + Google Style, com geração automática de documentação via Sphinx.

---

Estrutura do projeto

pep257_exemplo/
├── concursos/
│   ├── __init__.py   # docstring de pacote
│   └── models.py     # classes e funções com docstrings Google Style
├── docs/
│   ├── conf.py       # configuração do Sphinx
│   └── index.rst     # página inicial da documentação
├── requirements.txt
└── README.md

---

O que estudar neste projeto

Arquivo	O que observar
concursos/__init__.py	Docstring de pacote (uma linha)
concursos/models.py	Docstrings de módulo, classe, __init__, métodos e função
docs/conf.py	Extensões autodoc, napoleon e viewcode

Pontos-chave do Google Style

1. Resumo — primeira linha, imperativo, sem "Esta função..."
2. Linha em branco — separa o resumo do corpo e das seções
3. Args: — nome (tipo): descrição — self nunca é documentado
4. Returns: — tipo: descrição
5. Raises: — TipoDoErro: quando ocorre
6. Descrições específicas — nunca genéricas; devem mencionar o domínio do sistema

---

Como instalar e gerar a documentação

# 1. Clone o repositório
git clone https://github.com/seu-usuario/pep257-exemplo.git
cd pep257-exemplo

# 2. Instale as dependências
pip install -r requirements.txt

# 3. Gere a documentação HTML
cd docs
sphinx-build -b html . _build/html

# 4. Abra no navegador
# Acesse: docs/_build/html/index.html

---

Como verificar conformidade com pydocstyle

# Verifica todos os arquivos Python do pacote
pydocstyle --convention=google concursos/

Nenhuma saída = tudo correto.

---

Referências

• PEP 257 — Docstring Conventions
• Google Style Docstrings
• Sphinx autodoc
• Sphinx napoleon