Contribuir para este guia#
O Python Packaging User Guide dá as boas-vindas aos(às) contribuidores(as)! Existem muitas maneiras de ajudar, incluindo:
Lendo o guia e dando feedback
Revisando novas contribuições
Revisando conteúdo existente
Escrevendo novo conteúdo
Traduza o guia
A maior parte do trabalho no Python Packaging User Guide ocorre no repositório GitHub do projeto. Para começar, verifique a lista de issues abertos e pull requests. Se você está planejando escrever ou editar o guia, leia o guia de estilo.
Ao contribuir para o Python Packaging User Guide, espera-se que você siga o Código de Conduta da PSF.
Tipos de documentação#
Este projeto consiste em quatro tipos de documentação distintos com finalidades específicas. O projeto aspira seguir a o processo Diátaxis para criar documentação de qualidade. Ao propor novas adições ao projeto, escolha o tipo de documentação apropriado.
Tutoriais#
Os tutoriais são focados em ensinar ao leitor novos conceitos através da realização de um objetivo. Eles são guias passo a passo opinativos. Eles não incluem avisos ou informações estranhas. Exemplo de documento no estilo tutorial.
Guias#
Os guias são focados em realizar uma tarefa específica e podem assumir algum nível de conhecimento pré-requisito. Eles são semelhantes aos tutoriais, mas têm um foco estreito e claro e podem fornecer muitas advertências e informações adicionais, conforme necessário. Eles também podem discutir várias abordagens para realizar a tarefa. Exemplo de documento no estilo guia.
Discussões#
As discussões são focadas em compreensão e informação. Eles exploram um tópico específico sem um objetivo específico em mente. Exemplo de documento no estilo discussão.
Especificações#
As especificações são documentação de referência focada na documentação abrangente de uma interface acordada para interoperabilidade entre ferramentas de empacotamento. Exemplo de documento no estilo especificação.
Traduções#
Usamos Weblate para gerenciar as traduções deste projeto. Visite o projeto packaging.python.org no Weblate para contribuir.
Se você está tendo problemas enquanto trabalha nas traduções, relate o problema no GitHub.
Dica
Qualquer tradução deste projeto deve seguir a sintaxe reStructuredText.
Adicionando um idioma#
Se o seu idioma não estiver listado em packaging.python.org, clique no botão Iniciar nova tradução na parte inferior da lista de idiomas e adicione o idioma que deseja traduzir.
Seguindo a sintaxe reStructuredText#
Se você não está familiarizado com a sintaxe reStructuredText (RST), leia este guia antes de traduzir no Weblate.
Não traduza o texto em referências diretamente
Ao traduzir o texto em referências, não os traduza diretamente.
Errado: traduzir o texto a seguir diretamente:`some ref`_ -> `TRANSLATED TEXT HERE`_Correto: traduzir o texto a seguir em seu próprio idioma e adicionar a referência original:`some ref`_ -> `TRANSLATED TEXT HERE <some ref>`_
Construindo o guia localmente#
Embora não seja necessário contribuir, pode ser útil construir este guia localmente para testar suas alterações. Para construir este guia localmente, você precisará:
Nox. Você pode instalar ou atualizar o nox usando o
pip:python -m pip install --user nox
Python 3.11. Nossos scripts de construção são geralmente testados com Python 3.11. Consulte o Guia do mochileiro para as instruções de instalação do Python para instalar o Python 3.11 em seu sistema operacional.
Para construir o guia, execute o seguinte comando shell na pasta raiz do projeto:
nox -s build
Após a conclusão do processo, você pode encontrar a saída HTML no diretório ./build/html. Você pode abrir o arquivo index.html para ver o guia no navegador web, mas é recomendado servir o guia usando um servidor HTTP.
Você pode construir o guia e exibi-lo por meio de um servidor HTTP usando o seguinte comando:
nox -s preview
O guia poderá ser navegado em http://localhost:8000.
Onde o guia é disponibilizado#
O guia é disponibilizado via ReadTheDocs e a configuração está em https://readthedocs.org/projects/python-packaging-user-guide/.. É servido a partir de um domínio personalizado e guardado por Fast.ly.
Guia de estilo#
Este guia de estilo contém recomendações de como você deve escrever o Python Packaging User Guide. Antes de começar a escrever, revise-o. Seguindo o guia de estilo, suas contribuições ajudarão a formar um todo coeso e tornar mais fácil para que suas contribuições sejam aceitas no projeto.
Propósito#
O objetivo do Python Packaging User Guide é ser o recurso autorizado sobre como empacotar, publicar e instalar projetos Python usando as ferramentas atuais.
Escopo#
O guia destina-se a responder a perguntas e resolver problemas com recomendações precisas e focadas.
O guia não pretende ser abrangente e não pretende substituir a documentação de projetos individuais. Por exemplo, pip tem dezenas de comandos, opções e configurações. A documentação do pip descreve cada um deles em detalhes, enquanto este guia descreve apenas as partes do pip que são necessárias para concluir as tarefas específicas descritas neste guia.
Público-alvo#
O público-alvo deste guia é qualquer pessoa que use Python com pacotes.
Não se esqueça de que a comunidade Python é grande e acolhedora. Os leitores podem não compartilhar sua idade, sexo, educação, cultura e muito mais, mas eles merecem aprender sobre empacotamento tanto quanto você.
Em particular, tenha em mente que nem todas as pessoas que usam Python se consideram programadores. O público deste guia inclui astrônomos, pintores ou estudantes, bem como desenvolvedores de software profissionais.
Voz e tom#
Ao escrever este guia, esforce-se para escrever com uma voz que seja acessível e humilde, mesmo que você tenha todas as respostas.
Imagine que você está trabalhando em um projeto Python com alguém que sabe ser inteligente e habilidoso. Você gosta de trabalhar com eles e eles gostam de trabalhar com você. Essa pessoa fez uma pergunta e você sabe a resposta. Como você responde? É assim que você deve escrever este guia.
Aqui está uma verificação rápida: tente ler em voz alta para ter uma noção da voz e do tom de sua escrita. Parece algo que você diria ou parece que você está encenando um papel ou fazendo um discurso? Sinta-se à vontade para usar contrações e não se preocupe em seguir regras gramaticais complicadas. Você tem permissão para encerrar uma frase em uma preposição, se for assim que deseja encerrá-la.
Ao escrever o guia, ajuste seu tom de acordo com a seriedade e a dificuldade do tópico. Se você estiver escrevendo um tutorial introdutório, não há problema em fazer uma piada, mas se estiver cobrindo uma recomendação de segurança sensível, convém evitar piadas completamente.
Convenções e mecânicas#
- Escreva para o leitor
Ao dar recomendações ou etapas a serem seguidas, dirija-se ao leitor como você ou use o humor imperativo.
Errado: Para instalá-lo, o usuário executa…Certo: Você pode instalá-lo executando…Certo: Para instalá-lo, execute…- Presuma
Evite fazer suposições não declaradas. Ler na web significa que qualquer página do guia pode ser a primeira página do guia que o leitor vê. Se você vai fazer suposições, diga quais suposições você vai fazer.
- Faça uso generoso de referência cruzada
Na primeira vez que você mencionar uma ferramenta ou prática, coloque um link para a parte do guia que a cobre ou para um documento relevante em outro lugar. Economize uma pesquisa ao leitor.
- Respeite as práticas de nomenclatura
Ao nomear ferramentas, sites, pessoas e outros nomes próprios, use a capitalização de sua preferência.
Errado: Pip usa…Certo: pip usa…Errado: …hospedado no github.Certo: …hospedado no GitHub.- Use um estilo de gênero neutro
Frequentemente, você se dirigirá ao leitor diretamente com you, your e yours. Caso contrário, use pronomes de gênero neutro they, their e theirs ou evite os pronomes completamente.
Errado: A maintainer uploads the file. Then he…Certo: A maintainer uploads the file. Then they…Certo: A maintainer uploads the file. Then the maintainer…- Títulos
Escreva títulos que usem palavras que o leitor esteja procurando. Uma boa maneira de fazer isso é fazer com que o cabeçalho responda a uma pergunta implícita. Por exemplo, um leitor pode querer saber How do I install MyLibrary?, de forma que um bom título pode ser Install MyLibrary.
Nos cabeçalhos das seções, use letras maiúsculas e minúsculas. Em outras palavras, escreva os cabeçalhos da mesma forma que escreveria uma frase típica.
Errado: Things You Should Know About PythonCerto: Things you should know about Python- Números
No corpo do texto, escreva os números de um a nove como palavras. Para outros números ou números nas tabelas, use numerais.