Adicione um arquivo README ao seu pacote Python#
Nas lições anteriores você aprendeu:
Objetivos de aprendizagem
Nesta lição você aprenderá:
Como adicionar um arquivo README.md ao seu pacote.
Quais são os elementos principais de um arquivo README.md.
O que é um arquivo README?#
O arquivo README.md é o README do projeto e fica na raiz do diretório do projeto. Ele ajuda o usuário a entender:
O nome do seu pacote
O que o pacote faz. Seu README deve deixar claro o(s) problema(s) que seu software resolve e o público-alvo.
O «estado» atual de desenvolvimento do pacote (por meio de badges)
Como começar a usar seu pacote.
Como contribuir para o seu pacote
Como citar seu pacote
Seu arquivo README.md é importante, pois costuma ser a primeira coisa que alguém vê antes de instalar seu pacote. O README também é usado para popular a página do PyPI.
Note que não há uma estrutura de conteúdo específica para arquivos README. No entanto, este tutorial descreve as seções que sugerimos incluir no seu README.
Crie um arquivo README.md para o seu pacote#
É hora de adicionar um arquivo README.md ao diretório do seu projeto.
Passo 0: Crie um arquivo README#
Para começar, se ainda não tiver um arquivo README.md no diretório do projeto, crie um.
Dica
Se você criou o diretório do projeto a partir de
um repositório no GitHub online
usando
hatch init
Então você pode já ter um arquivo README.MD no diretório do projeto.
Passo 1: Adicione o nome do seu pacote como título do README#
No topo do arquivo README.md, adicione o nome do seu pacote.
Se estiver usando markdown, deve ser um título H1 (header 1), indicado com um único #.
# Package-title-here
Passo 2: adicione badges ao topo do seu arquivo README#
É comum os mantenedores adicionarem badges ao topo dos arquivos README. Os badges permitem que você e os pessoas usuárias do pacote acompanhem coisas como:
Falhas em builds de documentação e testes.
Versões do seu pacote no PyPI e no conda.
Se o seu pacote foi revisado e validado por uma organização como pyOpenSci e/ou JOSS.
Se você já publicou seu pacote em pypi.org, pode usar shields.io para criar um badge de versão do pacote. Esse badge será atualizado dinamicamente conforme você publica novas versões do pacote no PyPI.
Caso contrário, pode deixar o topo vazio por enquanto e adicionar badges ao README mais tarde, quando fizer sentido.
Passo 3: Adicione uma descrição do que seu pacote faz#
Abaixo dos badges (se houver), adicione um trecho de texto com uma visão geral fácil de entender do que seu pacote faz.
Mantenha esta seção curta.
Tente evitar jargão.
Defina termos técnicos que usar para tornar a descrição acessível a mais pessoas.
Lembre-se: quanto mais pessoas entenderem o que seu pacote faz, mais pessoas o usarão.
Passo 4: Adicione instruções de instalação do pacote#
Em seguida, adicione instruções que expliquem aos usuários como instalar seu pacote.
Por exemplo, dá para instalar o pacote com pip? python -m pip install packagename
ou conda?
conda install -c conda-forge packagename.
Se você ainda não publicou seu pacote em pypi.org, pode pular esta seção e voltar depois para adicionar essas instruções.
Passo 5: Configuração adicional#
Em alguns casos, os usuários do pacote podem precisar instalar manualmente outras ferramentas para usá-lo. Nesse caso, adicione uma seção sobre configuração adicional ao README.
Aqui, documente brevemente (ou inclua um link para documentação sobre) qualquer configuração adicional necessária para usar seu pacote. Isso pode incluir:
informações de autenticação, se aplicável ao seu pacote.
instalação de ferramentas adicionais, como GDAL.
Nota
Muitos pacotes não precisam de uma seção de configuração adicional no README. Nesse caso, você sempre pode pular esta seção.
Passo 6: Adicione uma seção de primeiros passos#
Em seguida, adicione uma seção de primeiros passos. Nela, inclua um pequeno exemplo de código que demonstre o import e o uso de alguma funcionalidade do seu pacote.
Forneça um trecho de código totalmente funcional, se possível
É importante tentar tornar os exemplos de código que você fornece aos usuários o mais úteis possível.
Forneça um exemplo de código para copiar/colar que funcione como está quando colado em um Jupyter Notebook ou arquivo .py, se isso for possível.
Se forem necessários tokens e outras etapas para executar seu pacote, deixe claras quais são.
Para o pyosPackage, uma demonstração curta de primeiros passos pode ficar assim:
>>> from pyospackage.add_numbers import add_num
>>> add_num(1, 2)
3
Ou pode ser simplesmente um link para um tutorial de primeiros passos que você criou. Se ainda não tiver isso, pode deixar em branco por enquanto.
Este também seria um ótimo lugar para adicionar links para tutoriais que ajudem os usuários a entender como usar seu pacote em workflows comuns.
Passo 7: Seção de comunidade#
A seção de comunidade do README é o lugar para incluir informações para usuários que queiram se envolver com o projeto. Esse engajamento provavelmente acontecerá em uma plataforma como GitHub ou GitLab.
Na seção de comunidade, você adicionará links para o guia de contribuição e para o CODE_OF_CONDUCT.md. Você criará um arquivo de código de conduta na próxima lição.
Conforme seu pacote cresce, você também pode ter um link para um guia de desenvolvimento que contribuidores e a equipe de mantenedores seguirão. O guia de desenvolvimento descreve como realizar tarefas de manutenção, como:
executar testes
fazer releases do pacote
gerar documentação
e mais.
Passo 8: Informações de citação#
Por fim, é importante informar aos usuários como citar seu pacote. Você pode comunicar informações de citação de algumas formas diferentes.
Você pode usar uma ferramenta como o zenodo para criar um DOI e informações de citação associadas ao seu pacote se ele estiver hospedado em uma plataforma como o GitHub. Confira este tutorial curto que explica como configurar isso.
Alternativamente, se você submeter seu pacote a um processo de revisão por pares, como o liderado pelo pyOpenSci. Depois de aceito pelo pyOpenSci, se seu pacote estiver no escopo, você pode ser aceito pelo Journal of Open Source Software e obter um DOI cross-ref por meio da nossa parceria com o Journal of Open SourceSoftware.
O README finalizado#
Seu arquivo README.md finalizado deve ficar parecido com isto:
# pyosPackage
[](https://doi.org/10.5281/zenodo.8365068)
[](https://github.com/pyOpenSci/software-submission/issues/115)
## What pyosPackage does
Short description here using non-technical language that describes what your package does.
## How to install pyosPackage
:::{todo}
- when i add more to the pyos package this can use that readme>
:::
To install this package run:
`python -m pip install pyosPackage`
## OPTIONAL - if you have additional setup instructions add them here. If not, skip this section.
## Get started using pyosPackage
Here add a quick code demo showing a user how to use the package after it is installed.
```python
>>> from pyospackage.add_numbers import add_num
>>> add_num(1, 2)
3
```
You can also add any links to tutorials in your documentation here.
## Community
Add information here about contributing to your package. Be sure to add links to your
`CODE_OF_CONDUCT.md` file and your development guide. For now this section might be
empty. You can go back and fill it in later.
## How to cite pyosPackage
citation information here
Encerramento#
É importante considerar as informações que um novo usuário ou contribuidor pode precisar ao criar seu arquivo README.md. Embora não exista um template perfeito, acima está um conjunto de recomendações para quando você está começando. Você pode precisar adicionar outros elementos a este arquivo conforme desenvolve mais o pacote e uma comunidade começa a usá-lo.
Na próxima lição, você adicionará um arquivo LICENSE ao seu pacote Python. Um arquivo de licença é fundamental, pois informa aos usuários como podem (e não podem) usar seu pacote legalmente. Ele também:
Gera confiança com seus usuários
Desencoraja o uso indevido do seu pacote e do código associado