Contribuindo para o Sphinx¶

Existem muitas maneiras de contribuir para o Sphinx, seja enviando relatórios de erros ou solicitações de recursos, escrevendo nova documentação ou enviando patches para comportamento novo ou corrigido. Este guia serve para ilustrar como você pode começar com isso.

Obter ajuda¶

A comunidade do Sphinx mantém uma série de listas de discussão e canais de IRC.

Stack Overflow com a tag python-sphinx: Perguntas e respostas sobre o uso e o desenvolvimento.
Q&A no GitHub Discussions: Fórum no estilo “perguntas e respostas” para discussões.
sphinx-users <sphinx-users@googlegroups.com>: Lista de discussão para suporte a usuário(a).
sphinx-dev <sphinx-dev@googlegroups.com>: Lista de discussão para discussões relacionadas a desenvolvimento.
#sphinx-doc no irc.libera.chat: Canal IRC para perguntas desenvolvimento e suporte a usuário(a).

Relatórios de bugs e solicitação de recursos¶

Se você encontrou um problema com o Sphinx ou tem uma ideia para um novo recurso, envie-a para o rastreador de problemas no GitHub.

Para relatórios de bugs, inclua a saída produzida durante o processo de construção e também o arquivo de log criado pelo Sphinx após encontrar uma exceção não tratada. O local deste arquivo deve ser mostrada no final da mensagem de erro. Por favor, também inclua a saída de sphinx-build --bug-report.

Incluindo or informando um link para os arquivos fonte envolvidos podem ajudar na correção da ocorrência. Se possível, tente criar e postar um projeto restrito para reproduzir e exibir o erro.

Contribuir com código¶

O código-fonte do Sphinx é gerenciado usando Git e está hospedado no GitHub. A maneira recomendada para novos contribuidores enviarem código para o Sphinx é fazer o fork deste repositório e enviar uma pull request após fazer commit das alterações em seu fork. A pull request precisará então ser aprovada por um dos desenvolvedores principais antes de ser incorporada ao repositório principal.

Primeiros passos¶

Antes de iniciar um patch, recomendamos verificar se há problemas em aberto ou abrir um novo problema para iniciar uma discussão sobre uma ideia de recurso ou um bug. Se você se sentir desconfortável ou incerto sobre um problema ou suas alterações, sinta-se à vontade para iniciar uma discussão.

Passos básicos necessários para iniciar no desenvolvimento no Sphinx.

Crie uma conta no GitHub.
Faça um fork do repositório principal do Sphinx (sphinx-doc/sphinx) usando a interface do GitHub.

Clone o repositório fork para seu computador.

git clone https://github.com/<USERNAME>/sphinx
cd sphinx

Install uv and set up your environment.

We recommend using uv for dependency management. Install it with:
```
python -m pip install -U uv
```
Then, set up your environment:
```
uv sync
```
Alternative: If you prefer not to use uv, you can use pip:
```
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
```
Crie um novo ramo de trabalho. Escolha qualquer nome que desejar.
```
git switch -c feature-xyz
```
Hack, trabalhe, trabalhe, escreva.

Escreva seu código junto com testes que mostram que o bug foi corrigido ou que o recurso funciona conforme o esperado.
Adicione um marcador a CHANGES.rst se a correção ou recurso não for trivial (pequenas atualizações de documentos, correções de erros de digitação) e, em seguida, faça o commit:
```
git commit -m 'Add useful new feature that does this.'
```
Faça push das alterações no branch para o seu fork do repositório no GitHub:
```
git push origin feature-xyz
```
Submeta uma pull request do seu branch para o branch master.

O GitHub reconhece certas frases que podem ser usadas para atualizar automaticamente o rastreador de problemas. Por exemplo, incluir ‘Closes #42’ no corpo do seu pull request fechará o issue #42 se o PR for mesclado.
Aguarde até que um core developer ou contribuidor revise suas modificações.

Você pode ser solicitado a responder a comentários sobre a revisão. Nesse caso, evite forçar o push para o branch. O Sphinx usa a estratégia squash merge ao mesclar PRs, portanto, os commits subsequentes serão todos combinados.

Estilo de codificação¶

Siga estas diretrizes ao escrever código para o Sphinx:

Tente usar o mesmo estilo de código usado no restante do projeto.
Para modificações não triviais, favor atualizar arquivo CHANGES.rst. Caso suas atualizações modifiquem comportamentos, favor documentar isso.
Novas funcionalidades devem ser documentadas. Incluir exemplos e usos onde apropriado. Se possível, incluir um exemplo do que é exibido na geração de saída.
Ao adicionar uma nova variável de configuração, certifique-se de documentá-la e atualizar sphinx/cmd/quickstart.py se ela for importante o suficiente.
Adicione testes de unidade apropriados.

As verificações de estilo e tipo podem ser executadas da seguinte forma:

uv run ruff check
uv run ruff format
uv run mypy

Testes de unidade¶

Sphinx é testado usando pytest para código Python e Jasmine para JavaScript.

Para executar testes de unidade Python, recomendamos usar tox, que fornece vários alvos e permite testes em vários ambientes Python diferentes:

Para listar todos os alvos possíveis:
```
tox -av
```
To run unit tests for a specific Python version, such as Python 3.14:
```
tox -e py314
```
Argumentos para pytest podem ser passados via tox, por exemplo, para executar um teste específico:
```
tox -e py314 tests/test_module.py::test_new_feature
```

Você também pode testar instalando dependências em seu ambiente local:

uv run pytest

Or with pip:

python -m pip install . --group test
pytest

Para executar testes de JavaScript, use npm:

npm install
npm run test

Dica

jasmine requer um binário do Firefox para usar como navegador de teste.

Em sistemas Unix, você pode verificar a presença e a localização do binário firefox na linha de comando executando command -v firefox.

Novos testes de unidade devem ser incluídos no diretório tests/ onde necessário:

Para corrigir bugs, primeiro adicionar um teste que falha seu suas modificações e passe após suas modificações.
Os testes que precisam de uma execução de sphinx-build devem ser integrados em um dos módulos de teste existentes, se possível.
Os testes devem ser rápidos e testar apenas os componentes relevantes, pois pretendemos que o conjunto de testes não demore mais de um minuto para ser executado. Em geral, evite usar o fixture app e app.build() a menos que um teste de integração completo seja necessário.

Adicionado na versão 1.8: O Sphinx também executa testes de JavaScript.

Alterado na versão 1.5.2: O Sphinx trocou de nose para pytest.

Contribuir com documentação¶

Contribuir para a documentação envolve modificar os arquivos fonte encontrados na pasta doc/. Para começar, você deve primeiro seguir Primeiros passos e depois seguir os passos abaixo para trabalhar com a documentação.

As seções a seguir descrevem como começar a contribuir com documentação, bem como os principais aspectos de algumas ferramentas diferentes que usamos.

Construir a documentação¶

Para construir a documentação, execute o seguinte comando:

sphinx-build -M html ./doc ./build/sphinx --fail-on-warning

Isto irá analisar os arquivos fonte da documentação do Sphinx e gerar HTML para você visualizar em build/sphinx/html.

Você também pode construir uma versão live da documentação que pode ser visualizada no navegador. Ele detectará alterações e recarregará a página sempre que você fizer edições. Para fazer isso, use sphinx-autobuild para executar o comando a seguir:

sphinx-autobuild ./doc ./build/sphinx/

Traduções¶

As partes das mensagens no Sphinx que vão para as construções são traduzidas em várias localidades. As traduções são mantidas como arquivos gettext .po traduzidos do modelo mestre sphinx/locale/sphinx.pot.

These Sphinx core messages are translated using the online Transifex platform.

Translated strings from the platform are pulled into the Sphinx repository by a maintainer before a new release.

We do not accept pull requests altering the translation files directly. Instead, please contribute translations via the Transifex platform.

Translations notes for maintainers¶

The transifex CLI (tx) can be used to pull translations in .po format from Transifex. To do this, go to sphinx/locale and then run tx pull -f -l LANG where LANG is an existing language identifier. It is good practice to run python utils/babel_runner.py update afterwards to make sure the .po file has the canonical Babel formatting.

Sphinx uses Babel to extract messages and maintain the catalog files. The utils directory contains a helper script, utils/babel_runner.py.

Use python babel_runner.py extract para atualizar modelo .pot.
Use python babel_runner.py update para atualizar todos os catálogos de idiomas em sphinx/locale/*/LC_MESSAGES com mensagens do arquivo modelo.
Use python babel_runner.py compile para compilar os arquivos .po em arquivos binários .mo e arquivos .js.

Quando arquivo .po for submetido, executar python babel_runner.py compile para o fazer commit de ambos catálogos fonte e compilados.

When a new locale is added, add a new directory with the ISO 639-1 language identifier and put sphinx.po in there. Don’t forget to update the possible values for language in doc/usage/configuration.rst.

Dicas de depuração¶

Apague o cache de construção antes de construir documentos, caso tenha feito modificações no código, usar o comando make clean ou usar a opção sphinx-build --fresh-env.
Use a opção sphinx-build --pdb para executar pd em exceções.
Use node.pformat() e node.asdom().toxml() para gerar representação impressa da estrutura do documento.
Defina a variável de configuração keep_warnings para True assim os avisos serão exibidos na saída gerada.
Configure a variável nitpicky para True assim Sphinx irá respeitar referências sem alvos conhecidos.
Define as opções de depuração no arquivo de configuração do Docutils.

Atualizando arquivos gerados¶

Algoritmos de steeming em JavaScript em sphinx/search/non-minified-js/*.js e arquivos de stopword em sphinx/search/_stopwords/ são gerados a partir do projeto Snowball executando utils/generate_snowball.py.

Arquivos minificados em sphinx/search/minified-js/*.js são gerados a partir de arquivos não minificados usando uglifyjs (instalado via npm). Veja sphinx/search/minified-js/README.rst
Os arquivos searchindex.js encontrados nos diretórios tests/js/fixtures/* são gerados usando o construtor HTML padrão do Sphinx nos projetos de entrada correspondentes encontrados em tests/js/roots/*. Os fixtures fornecem dados de teste usados pelos testes de unidade JavaScript do Sphinx, e podem ser regenerados executando o script utils/generate_js_fixtures.py.