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

Configure um ambiente virtual.

Isto não é necessário para testes unitários, graças ao tox, mas é necessário se você deseja executar sphinx-build localmente ou executar testes unitários sem a ajuda do tox:
```
virtualenv ~/.venv
. ~/.venv/bin/activate
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.

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:

ruff check .
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
```
Para executar testes de unidade para uma versão específica do Python, como Python 3.13:
```
tox -e py313
```
Argumentos para pytest podem ser passados via tox, por exemplo, para executar um teste específico:
```
tox -e py313 tests/test_module.py::test_new_feature
```

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

pip install .[test]

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.

Sphinx usa Babel para extrair mensagens e manter os arquivos do catálogo. O diretório utils contém um script auxiliar, 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.

Quando uma nova localidade é enviada, adicione um novo diretório com o identificador de idioma ISO 639-1 e coloque sphinx.po nele. Não se esqueça de atualizar os valores possíveis para language em doc/usage/configuration.rst.

As mensagens principais do Sphinx também podem ser traduzidas no Transifex. A ferramenta cliente tx, que é fornecida pelo pacote Python transifex_client, pode ser usada para extrair traduções no formato .po do Transifex. Para fazer isso, vá para sphinx/locale e então execute tx pull -f -l LANG onde LANG é um identificador de idioma existente. É uma boa prática executar python babel_runner.py update posteriormente para garantir que o arquivo .po tenha a formatação canônica do Babel.

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 stemming JavaScript em sphinx/search/non-minified-js/*.js são gerados usando snowball clonando o repositório, executando make dist_libstemmer_js e então descompactando o tarball que é gerado no diretório dist.

Arquivos minificados em sphinx/search/minified-js/*.js são gerados a partir de arquivos não minificados usando uglifyjs (instalado via npm), com a opção -m para habilitar a manipulação.
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.