Skip to content

Build Instructions

These instructions only apply if you want to build a local/offline version of the documentation. This is convenient for more elaborate edits, using an editor and workflow of your choice.

Install required software:

  1. Download the Python installation package for Windows.
  2. Install Python with the installation wizard. Make sure to enable the "Add Python to PATH" option.
  3. Download and install Git for Windows.

Set up Git LFS
Open a command line window and run the following command: 

git lfs install

Clone the documentation sources: 

git clone https://projects.blender.org/blender/blender-developer-docs.git developer-docs
cd developer-docs
This will clone the sources into a developer-docs directory inside the current one and change into it.

Recommended: Setup and activate a virtual Python environment where dependencies will be installed: 

python3 -m venv .venv
.venv/Scripts/activate # (1)!

  1. Repeat this command to re-activate the virtual environment whenever you open a new terminal session to build the documentation.

Install all dependencies, such as Material for MkDocs: 

python -m pip install -r requirements.txt

Install required software
Install PIP, Git and Git LFS. When using Homebrew, run the following commands in the terminal: 

python3 -m ensurepip
brew install git git-lfs

Set up Git LFS
Open a terminal and run the following command: 

git lfs install

Clone the documentation sources: 

git clone https://projects.blender.org/blender/blender-developer-docs.git developer-docs
cd developer-docs
This will clone the sources into a developer-docs directory inside the current one and changes into it.

Recommended: Setup and activate a virtual Python environment where dependencies will be installed: 

python3 -m venv .venv
source .venv/bin/activate # (1)!

  1. Repeat this command to re-activate the virtual environment whenever you open a new terminal session to build the documentation.

Install all dependencies, such as Material for MkDocs: 

python3 -m pip install -r requirements.txt

Install required software
Install Python, PIP, Git and Git LFS using your package manager:

sudo apt install python3 python3-pip git git-lfs

sudo yum install python python-pip git git-lfs

sudo pacman -S python python-pip git git-lfs

Set up Git LFS:

git lfs install --skip-repo

Clone the documentation sources:

git clone https://projects.blender.org/blender/blender-developer-docs.git developer-docs
cd developer-docs

This will clone the sources into a developer-docs directory inside the current one and change into it.

Recommended: Setup and activate a virtual Python environment where dependencies will be installed: 

python3 -m venv .venv
source .venv/bin/activate # (1)!

  1. Repeat this command to re-activate the virtual environment, whenever you open a new terminal to build the documentation.

Install all dependencies, such as Material for MkDocs: 

python3 -m pip install -r requirements.txt

Build this documentation with live reloading: 

mkdocs serve --dirty # (1)!

  1. Use the --dirty option when editing single pages, as it makes rebuilds much faster. It only rebuilds the HTML for modified files. Do not use it when modifying the navigation hierarchy, since the option often fails to reflect such changes.

Alternatively mkdocs build will generate the documentation as HTML into a site/ directory. Simply open site/index.html in a browser.

Updating

The following commands assume you're inside the developer-docs directory.

Update the documentation sources:

git pull --rebase

Re-enable Virtual Python Environment

If you've followed the recommendation above of installing a virtual Python environment, you need to enable it for every new terminal session.

.venv/Scripts/activate

source .venv/bin/activate

source .venv/bin/activate

Update Dependencies:

python -m pip install -r requirements.txt

python3 -m pip install -r requirements.txt

python3 -m pip install -r requirements.txt

Dependencies should be updated regularly. Especially on dependency related build errors.

Build this documentation with live reloading
Use the same build commands as explained above, for example: 

mkdocs serve --dirty