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.

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 no Sphinx ou tem uma ideia para um novo recurso, envie-o para o rastreador de problemas no GitHub ou discuta-o na lista de discussão sphinx-dev.

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.

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 enviar um e-mail para a lista de discussão sphinx-dev.

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

  1. Crie uma conta no GitHub.

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

  3. Clone o repositório fork para seu computador.

    git clone https://github.com/USERNAME/sphinx
    cd sphinx
    
  4. Faça o checkout para o branch apropriado.

    O Sphinx adota o Versionamento Semântico 2.0.0 (refs: https://semver.org/lang/pt-BR/ ).

    Para alterações que preservam a compatibilidade retroativa da API e dos recursos, elas devem ser incluídas na próxima versão MENOR, use a ramificação A.x:

    git checkout A.x
    

    Para alterações substanciais incompatíveis ou outras que devem aguardar até a próxima liberação MAIOR, use o branch master.

    Para um lançamento urgente, um novo branch PATCH deve ser ramificado a partir da tag de lançamento mais recente (veja Processo de lançamento do Sphinx para detalhes).

  5. 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 .
    
  6. Crie um novo ramo de trabalho. Escolha qualquer nome que desejar.

    git checkout -b feature-xyz
    
  7. 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.

  8. 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 '#42: Add useful new feature that does this.'
    

    O GitHub reconhece certas frases que podem ser usadas para atualizar automaticamente o rastreador de problemas. Por exemplo:

    git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
    

    fecharia o issue #42.

  9. Faça push das alterações no branch para o seu fork do repositório no GitHub:

    git push origin feature-xyz
    
  10. Submeta uma pull request do seu branch para o respectivo branch (master ou A.x).

  11. Aguarde até que um core developer 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 tests de unidade apropriados.

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

ruff check .
mypy sphinx/

Testes de unidade

Sphinx é testado usando pytest para código Python e Karma 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.10:

    tox -e py310
    
  • Para executar testes de unidade para uma versão específica do Python e ativar avisos de descontinuação para que sejam mostrados na saída do teste:

    PYTHONWARNINGS=error tox -e py310
    
  • Argumentos para pytest podem ser passados ​​via tox, por exemplo, para executar um teste específico:

    tox -e py310 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

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

Para sistemas baseados em Unix, você pode especificar o caminho para o binário do Firefox usando:

FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test

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 do sphinx-build devem ser integrados em um dos módulos de teste existentes, se possível. Novos testes que para @with_app e depois build_all para algumas asserções não são bons desde o conjunto de testes não demore mais de um minuto para ser executado.

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

Adicionado na versão 1.6: sphinx.testing é adicionado como experimental.

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

Funções de utilidade e os fixtures do pytest para testes são fornecidos em sphinx.testing. Se você é um desenvolvedor de extensões Sphinx, você pode escrever testes de unidade usando o pytest. Neste momento, o sphinx.testing ajudará sua implementação de teste.

Como usar as fixtures do pytest que são fornecidos pelo sphinx.testing? Você pode exigir 'sphinx.testing.fixtures' em seus módulos de teste ou em arquivos conftest.py como este:

pytest_plugins = 'sphinx.testing.fixtures'

Se você quiser saber o uso mais detalhado, consulte tests/conftest.py e outros arquivos test_*.py sob o diretório tests.

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 -W --keep-going

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, execute o seguinte comando:

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 -E.

  • Use a opção sphinx-build -P 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.

  • Algoritmos de stemming JavaScript em sphinx/search/non-minified-js/*.js são gerados usando snowball <https://github.com/snowballstem/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.