Developer's guide
====================

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

Contributing to the codebase
-------------------------------

1. Fork the `github repository <https://github.com/smegason/Goo>`__. 

2. Clone your fork repository within VSCode. 

3. Install libraries: follow the steps of the `installation guide <https://smegason.github.io/Goo/getting_started/installation.html>`__. 

4. Install the `Blender developer's extension <https://marketplace.visualstudio.com/items?itemName=JacquesLucke.blender-development>`__ 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.

.. code-block:: bash

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

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

5. 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

.. code-block:: bash

    cd docs

3. Modify source files: make modifications to the source .rst files or to the codebase. Code documentation follows `sphynx <https://www.sphinx-doc.org/en/master/>`__ 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`. 

.. literalinclude:: ../../Makefile
   :language: make

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

.. code-block:: bash

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

5. 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: 
    
.. code-block:: bash

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