Setting up a development environment¶
Contributing to BeeWare Docs Tools requires you to set up a development environment.
Prerequisites¶
You'll need to install the following prerequisites.
BeeWare Docs Tools requires Python 3.10+. You will also need
a method for managing virtual environments (such as venv).
You can verify the version of Python that you have installed by running:
$ python3 --version
If you have more than one version of Python installed, you may need to replace
python3 with a specific version number (e.g., python3.13)
We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on macOS often lag usually aren't available for recently released stable Python versions.
BeeWare Docs Tools requires Python 3.10+. You will also need
a method for managing virtual environments (such as venv).
You can verify the version of Python that you have installed by running:
$ python3 --version
If you have more than one version of Python installed, you may need to replace
python3 with a specific version number (e.g., python3.13)
We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on Linux often lag usually aren't available for recently released stable Python versions.
BeeWare Docs Tools requires Python 3.10+. You will also need
a method for managing virtual environments (such as venv).
You can verify the version of Python that you have installed by running:
C:\...>py -3 --version
If you have more than one version of Python installed, you may need to replace
the -3 with a specific version number (e.g., -python3.13)
We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on Windows often lag usually aren't available for recently released stable Python versions.
tl;dr - Quick start¶
Create your dev environment by running:
$ git clone https://github.com/beeware/beeware-docs-tools.git
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ . .venv/bin/activate
(.venv) $ python -m pip install -U pip
(.venv) $ python -m pip install -Ue . --group dev
(.venv) $ pre-commit install
$ git clone https://github.com/beeware/beeware-docs-tools.git
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ . .venv/bin/activate
(.venv) $ python -m pip install -U pip
(.venv) $ python -m pip install -Ue . --group dev
(.venv) $ pre-commit install
C:\...>git clone https://github.com/beeware/beeware-docs-tools.git
C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) C:\...>python -m pip install -U pip
(.venv) C:\...>python -m pip install -Ue . --group dev
(.venv) C:\...>pre-commit install
Invoke checks and tests by running:
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
Set up your development environment¶
The recommended way of setting up your development environment for BeeWare Docs Tools is to use a virtual environment, and then install the development version of BeeWare Docs Tools and its dependencies.
Clone the BeeWare Docs Tools repository¶
Next, go to the BeeWare Docs Tools page on GitHub, and, if you haven't already, fork the repository into your own account. Next, click on the "<> Code" button on your fork. If you have the GitHub desktop application installed on your computer, you can select "Open with GitHub Desktop"; otherwise, copy the HTTPS URL provided, and use it to clone the repository to your computer using the command line:
Fork the BeeWare Docs Tools repository, and then:
$ git clone https://github.com/<your username>/beeware-docs-tools.git
(substituting your GitHub username)
Fork the BeeWare Docs Tools repository, and then:
$ git clone https://github.com/<your username>/beeware-docs-tools.git
(substituting your GitHub username)
Fork the BeeWare Docs Tools repository, and then:
C:\...>git clone https://github.com/<your username>/beeware-docs-tools.git
(substituting your GitHub username)
Create a virtual environment¶
To set up a virtual environment and upgrade pip, run:
$ 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
Your prompt should now have a (.venv) prefix in front of it.
Install BeeWare Docs Tools¶
Now that you have the source code, you can do an editable install of BeeWare Docs Tools into your development environment. Run the following command:
(.venv) $ python -m pip install -Ue . --group dev
(.venv) $ python -m pip install -Ue . --group dev
(.venv) C:\...>python -m pip install -Ue . --group dev
Enable pre-commit¶
BeeWare Docs Tools uses a tool called pre-commit to identify simple issues and standardize code formatting. It does this by installing a git hook that automatically runs a series of code linters prior to finalizing any git commit. To enable pre-commit, run:
(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit
(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit
(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit
Now you are ready to start hacking on BeeWare Docs Tools!