Developer’s guide

We recommend using Visual Studio Code (VSCode) as code editor.

Contributing to the codebase

  1. Fork the github repository.

  2. Clone your fork repository within VSCode.

  3. Install libraries: follow the steps of the installation guide.

  4. Install the Blender developer’s extension developed by Jacques Lucke inside VSCode.

Testing your code

We developed a suite of tests to ensure the correct functioning of the codebase. They do not cover all possible cases, but they are a good starting point. Also, they do not test the realism and accuracy of the physics simulations.

  1. We use pytest from within Blender’s Python interpreter to run tests.

  2. A suite of test cases can be found inside the tests folder.

  3. To run the suite of tests, open a terminal in VSCode and run the following command from the codebase root directory. Make sure to replace the path to the Blender executable with the correct path on your system.

/Applications/Blender-4.0.app/Contents/MacOS/Blender --background  --python-expr "import pytest; pytest.main(['-v', './tests'])"

  1. All tests should pass before submitting a pull request.

  2. If you are adding new features, please add tests to cover the new functionality. See the existing test cases for examples.

Update the documentation

  1. Install dependencies about outlined above

  2. In your local Goo codebase

cd docs

  1. Modify source files: make modifications to the source .rst files or to the codebase. Code documentation follows sphynx syntax.

4. Running the build Due to some dependencies from Blender (i.e. bpy), the build has to be ran from Blender using its Python interpreter. The docs directory contains a modified Makefile so that it manually uses Blender executable. It should be ready-to-use for MacOS users. Other platform users should modify the ‘SPHINXBUILD’ variable so that it points towards a Blender executable file path in Makefile.

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
# SPHINXBUILD   ?= sphinx-build
SPHINXBUILD = /Applications/Blender-4.1.app/Contents/MacOS/Blender --background --python blender_sphinx.py --
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

api:
	sphinx-apidoc -e -o "$(SOURCEDIR)" ../scripts/modules/

Then, running the build will update the documentation in the /build directory. It will also automatically update the library documentation using Sphynx’s automodule.

make clean # clean up the build directory
make html # populate the build directory

  1. Move the content of the docs/build/html` directory to the root of the gh-pages branch using a tmp/ folder on your local machine. Then push the changes to the remote repository with:

git add .
git commit -m "Update docs"
git push -f