Contribuindo com Sphinx

There are many ways you can contribute to Sphinx, be it filing bug reports or feature requests, writing new documentation or submitting patches for new or fixed behavior. This guide serves to illustrate how you can get started with this.

Getting help

The Sphinx community maintains a number of mailing lists and IRC channels.

Stack Overflow with tag python-sphinx

Questions and answers about use and development.

sphinx-users <sphinx-users@googlegroups.com>

Lista Distribuição para suporte usuário.

sphinx-dev <sphinx-dev@googlegroups.com>

Lista Distribuição para discussões relacionadas a desenvolvimento.

#sphinx-doc on irc.freenode.net

Canal IRC para questões desenvolvimento e suporte usuário.

Reportar Erros e Requisitar Funcionalidades

Se você encontrou um problema no Sphinx ou tem uma ideia para um novo recurso, envie-o para o issue tracker 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 compilação e também o arquivo de log criado pelo Sphinx após encontrar uma exceção não tratada. A localização 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.

Writing code

The Sphinx source code is managed using Git and is hosted on GitHub. The recommended way for new contributors to submit code to Sphinx is to fork this repository and submit a pull request after committing changes to their fork. The pull request will then need to be approved by one of the core developers before it is merged into the main repository.

Getting started

Before starting on a patch, we recommend checking for open issues or open a fresh issue to start a discussion around a feature idea or a bug. If you feel uncomfortable or uncertain about an issue or your changes, feel free to email the sphinx-dev mailing list.

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

  1. Crie uma conta no GitHub.

  2. Fork o repositório principal do Sphinx (sphinx-doc/sphinx) usando a interface do GitHub.

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

    git clone https://github.com/USERNAME/sphinx
    cd sphinx
    
  4. Faça o apropriado Checkout no ambiente.

    O Sphinx adota o Semantic Versioning 2.0.0 (refs: https://semver.org/).

    For changes that preserves backwards-compatibility of API and features, they should be included in the next MINOR release, use the A.x branch.

    git checkout A.x
    

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

    For urgent release, a new PATCH branch must be branched from the newest release tag (see Sphinx’s release process for detail).

  5. Configurar um ambiente virtual.

    This is not necessary for unit testing, thanks to tox, but it is necessary if you wish to run sphinx-build locally or run unit tests without the help of tox:

    virtualenv ~/.venv
    . ~/.venv/bin/activate
    pip install -e .
    
  6. Create a new working branch. Choose any name you like.

    git checkout -b feature-xyz
    
  7. Hack, trabalhe, trabalhe, escreva.

    Write your code along with tests that shows that the bug was fixed or that the feature works as expected.

  8. Add a bullet point to CHANGES if the fix or feature is not trivial (small doc updates, typo fixes), then commit:

    git commit -m '#42: Add useful new feature that does this.'
    

    GitHub recognizes certain phrases that can be used to automatically update the issue tracker. For example:

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

    pode fechar requerimento #42.

  9. Push changes in the branch to your forked repository on GitHub:

    git push origin feature-xyz
    
  10. Submit a pull request from your branch to the respective branch (master or A.x).

  11. Aguarde até que um desenvolvedor do núcleo revise suas modificações.

Coding style

Please follow these guidelines when writing code for Sphinx:

  • Try to use the same code style as used in the rest of the project.

  • Para modificações não triviais, favor atualizar arquivo CHANGES. 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.

  • Adicionar unidades de teste apropriadas.

Style and type checks can be run using tox:

tox -e mypy
tox -e flake8

Unit tests

Sphinx is tested using pytest for Python code and Karma for JavaScript.

To run Python unit tests, we recommend using tox, which provides a number of targets and allows testing against multiple different Python environments:

  • Para listar todos os alvos possíveis:

    tox -av
    
  • To run unit tests for a specific Python version, such as Python 3.6:

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

    PYTHONWARNINGS=all tox -e py36
    
  • Argumentos para pytest podem ser passados via tox, por exemplo, a fim de executar um teste específico:

    tox -e py36 tests/test_module.py::test_new_feature
    

You can also test by installing dependencies in your local environment:

pip install .[test]

To run JavaScript tests, use npm:

npm install
npm run test

Novos testes unitários 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 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 deve demorar mais de um minuto para ser executado.

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

Novo na versão 1.6: sphinx.testing is added as a experimental.

Alterado na versão 1.5.2: Sphinx was switched from nose to pytest.

Por fazer

The below belongs in the developer guide

Utility functions and pytest fixtures for testing are provided in sphinx.testing. If you are a developer of Sphinx extensions, you can write unit tests with using pytest. At this time, sphinx.testing will help your test implementation.

How to use pytest fixtures that are provided by sphinx.testing? You can require 'sphinx.testing.fixtures' in your test modules or conftest.py files like this:

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.

Writing documentation

Por fazer

Add a more extensive documentation contribution guide.

You can build documentation using tox:

tox -e docs

Traduções

The parts of messages in Sphinx that go into builds are translated into several locales. The translations are kept as gettext .po files translated from the master template sphinx/locale/sphinx.pot.

Sphinx uses Babel to extract messages and maintain the catalog files. It is integrated in setup.py:

  • Usar python setup.py extract_messages para atualizar modelo .pot.

  • Usar python setup.py update_catalog para atualizar todos os catálogos de idiomas em sphinx/locale/*/LC_MESSAGES com mensagens do arquivo modelo.

  • Usar python setup.py compile_catalog para compilar arquivos .po para arquivos binários .mo e arquivos .js.

Quando arquivo .po for submetido, executar o compile_catalog para o commit de ambos catálogos fonte e compilados.

When a new locale is submitted, 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.

The Sphinx core messages can also be translated on Transifex. There tx client tool, which is provided by the transifex_client Python package, 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 setup.py update_catalog afterwards to make sure the .po file has the canonical Babel formatting.

Debugging tips

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

  • Usar node.pformat() e node.asdom().toxml() para gerar representação impressa da estrutura do documento.

  • Definir a variável de configuração keep_warnings para True assim os avisos serão exibidos na saída gerada.

  • Configurar a variável nitpicky para True assim Sphinx irá respeitar referências sem alvos conhecidos.

  • Set the debugging options in the Docutils configuration file.

  • JavaScript stemming algorithms in sphinx/search/*.py (except en.py) are generated by this modified snowballcode generator. Generated JSX files are in this repository. You can get the resulting JavaScript files using the following command:

    npm install
    node_modules/.bin/grunt build # -> dest/*.global.js