Configurando um ambiente de desenvolvimento¶
A contribuição para BeeWare Docs Tools exige que configure um ambiente de desenvolvimento.
Pré-requisitos¶
Vai precisar de instalar os seguintes pré-requisitos.
BeeWare Docs Tools requer Python 3.10+. Também vai precisar de um método para gerir ambientes virtuais (como o venv).
Pode verificar a versão do Python que instalou correndo:
$ python3 --version
Se tiver mais de uma versão do Python instalada, pode ser necessário substituir python3 por um número de versão específico (por exemplo, python3.13)
Recomendamos evitar versões do Python lançadas recentemente (ou seja, versões que tenham um micro-número de versão ".0" ou ".1", como por exemplo, 3.14.0). Isto porque as ferramentas necessárias para dar suporte ao Python no macOS geralmente andam atrasadas e não estão disponíveis para as versões estáveis do Python lançadas recentemente.
BeeWare Docs Tools requer Python 3.10+. Também vai precisar de um método para gerir ambientes virtuais (como o venv).
Pode verificar a versão do Python que instalou correndo:
$ python3 --version
Se tiver mais de uma versão do Python instalada, pode ser necessário substituir python3 por um número de versão específico (por exemplo, python3.13)
Recomendamos evitar versões do Python lançadas recentemente (ou seja, versões que tenham um micro-número de versão ".0" ou ".1", como por exemplo, 3.14.0). Isto porque as ferramentas necessárias para dar suporte ao Python no Linux geralmente andam atrasadas e não estão disponíveis para as versões estáveis do Python lançadas recentemente.
BeeWare Docs Tools requer Python 3.10+. Também vai precisar de um método para gerir ambientes virtuais (como o venv).
Pode verificar a versão do Python que instalou correndo:
C:\...>py -3 --version
Se tiver mais de uma versão do Python instalada, pode ser necessário substituir o -3 por um número de versão específico (ex., -python3.13)
Recomendamos evitar versões do Python lançadas recentemente (ou seja, versões que tenham um micro-número de versão ".0" ou ".1", como por exemplo, 3.14.0). Isto porque as ferramentas necessárias para dar suporte ao Python no Windows geralmente andam atrasadas e não estão disponíveis para as versões estáveis do Python lançadas recentemente.
Configurar o seu ambiente de desenvolvimento¶
A maneira recomendada de configurar o seu ambiente de desenvolvimento para BeeWare Docs Tools é usar um ambiente virtual, e depois instalar a versão de desenvolvimento de BeeWare Docs Tools e as suas dependências.
Clonar o repositório BeeWare Docs Tools¶
Em seguida, vá para a página BeeWare Docs Tools no GitHub e, se ainda não o fez, bifurque o repositório na sua própria conta. Em seguida, clique no botão "<> Code" na sua bifurcação. Se tiver a aplicação de desktop GitHub instalada no seu computador, pode selecionar "Abrir com GitHub Desktop"; caso contrário, copie o URL HTTPS fornecido e use-o para clonar o repositório no seu computador usando a linha de comandos:
Faça uma bifurcação do repositório BeeWare Docs Tools, e depois:
$ git clone https://github.com/<seu nome de utilizador>/beeware-docs-tools.git
(substituindo o seu nome de utilizador do GitHub)
Faça uma bifurcação do repositório BeeWare Docs Tools, e depois:
$ git clone https://github.com/<seu nome de utilizador>/beeware-docs-tools.git
(substituindo o seu nome de utilizador do GitHub)
Faça uma bifurcação do repositório BeeWare Docs Tools, e depois:
C:\...>git clone https://github.com/<seu nome de utilizador>/beeware-docs-tools.git
(substituindo o seu nome de utilizador do GitHub)
Definir um repositório de autor¶
Depois de clonar a sua bifurcação, adicione o repositório BeeWare como um upstream remoto. Isto fornece ao seu clone local uma referência ao repositório original, facilitando a sincronização de atualizações ao longo do tempo.
Também vai precisar de etiquetas de upstream para que as ferramentas como o Toga e Briefcase possam resolver números de versão com precisão:
$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream
$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream
C:\...>git remote add upstream https://github.com/beeware/beeware-docs-tools.git
C:\...>git fetch --tags upstream
Se quiser que a sua bifurcação inclua essas etiquetas também, pode envia-las:
$ git push --tags
Isto pode ser útil se criar um clone fresco mais tarde e quiser que as etiquetas estejam disponíveis a partir da sua bifurcação.
Criar um ambiente virtual¶
Para configurar um ambiente virtual e atualizar o pip, execute:
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip
C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip
O seu aviso de comando agora deve ter um prefixo (.venv) na frente.
Instalar BeeWare Docs Tools¶
Agora que tem o código-fonte, pode fazer uma instalação editável de BeeWare Docs Tools no seu ambiente de desenvolvimento. Execute o seguinte comando:
(.venv) $ python -m pip install -U -e . --group dev
(.venv) $ python -m pip install -U -e . --group dev
(.venv) C:\...>python -m pip install -U -e . --group dev
Ativar a pré-submissão¶
BeeWare Docs Tools usa uma ferramenta chamada pre-commit para identificar problemas simples e normalizar a formatação do código. Ela faz isto ao instalar um gancho do git que executa automaticamente uma série de fibras de código antes de finalizar qualquer submissão ao git. Para ativar o pre-commit, execute:
(.venv) $ pre-commit install
pre-commit instalado em .git/hooks/pre-commit
(.venv) $ pre-commit install
pre-commit instalado em .git/hooks/pre-commit
(.venv) C:\...>pre-commit install
pre-commit instalado em .git/hooks/pre-commit
Agora está pronto para começar a mexer no BeeWare Docs Tools!