4. Contributing#

There are several ways to contribute to the project:

  • Submit code changes to the project by opening a Pull Request via Codeberg.

  • Test the add-on, report bugs and propose ideas for extra features via the issue tracker.

  • Help to improve the documentation and share your renderings made with Pohlke. Feel free to join the matrix group chat to get in touch with the team.

  • Rate the add-on ⭐⭐⭐⭐⭐ on the Blender extension platform.

4.1. Source Code#

To start developing, clone Pohlke from Codeberg and open the src/pohlke/ folder in your IDE.

Quickstart with VS Code#
git clone ssh://git@codeberg.org/AlICe_lab/pohlke.git
cd pohlke/src/pohlke
code .

Working becomes seamless with the Blender Development for Visual Studio Code extension. When starting Blender through VS Code the add-on is automatically installed and updated. This setup is presented in the video below.

For more information, check out the Extensions section from the Blender Developer Handbook. When using another IDE than VS Code, use a symlink to manually connect the code base with Blender. Updates of the code apply in Blender by reloading the scripts. Code completion can be achieved with the help of the fake-bpy-module.

4.1.1. Branching#

Developement is done on custom branches for each contribution. These branches are merged into dev. After beta testing, dev is merged into main.

Release branch main

pull request

Beta branch dev

pull request

Custom branches

feature

bugfix

documentation

…

Tip

When opening a pull request with new features, corresponding tests in /src/pohlke/tests/ are highly recommended. Before submitting changes, consider linting uv tool run ruff check --fix and formatting uv tool run ruff format the source files with ruff. Finally, consider updating the documentation and to indicate the changes made to the changelog.

4.1.2. Release#

Beta test releases are created from the dev branch and distributed on the Codeberg release page. Stable releases are created from the main branch and uploaded to the Blender extension platform, as well as distributed on Codeberg.

A Blender command line is used to build the add-on zip archive. The command retrieves necessary release information from the blender_manifest.toml file.

cd src/pohlke
blender --command extension build

4.2. Presets Catalogue#

Additional presets can be added easily by modifying a single file: presets.toml. You can do so by opening a pull request or suggesting the changes in an issue.

The presets.toml file contains all the available data to indicate a preset in the add-on’s UI dropdown field. The settings are organized by projection type [Axonometric] or [Oblique].

Example of a presets.toml file#
[AXONOMETRIC]
"Isometric (30°/30°)" = {alpha = 30, beta = 30}
"Dimetric  Pixel 1:2 (26.56°/26.56°)" = {alpha = 26.565, beta = 26.565}

[OBLIQUE]
"Military 1:1" = {alpha = 60 , beta = 30, shortening = 1}
"Military 3:4" = {alpha = 60 , beta = 30, shortening = 0.75}

You simply need to add a new line under the projection type of your choice. The alpha and beta values correspond to the angles in the projection plane. For the oblique settings, shortening corresponds to the reduction factor of the Z axis.

Warning

  • Axonometric projections cannot have the shortening parameter, and conversely for oblique projections.

  • Axonometric projections must include Isometric, Dimetric, or Trimetric in their name field.

4.3. Documentation#

The documentation is built with Sphinx. The API section is generated from the source code’s docstrings using autoapi. All necessary files to build the docs are in the docs/ directory. Once you have made your changes, build the documentation locally with the help of uv and the following command:

Building html docs with Sphinx#
cd docs
uv run --with-requirements requirements.txt sphinx-build -b html . build/_html

Open the build/_html/index.html file to see the documentation in your browser.