FLAME GPU 2 User Guide

This repository contains the content and build process for generating the FLAMEGPU2 user guide.

When building, it can optionally be linked to the main FLAMEGPU2 source repository to include doxygen generated API documentation.

The FLAME GPU 2 userguide and API docs can be found at docs.flamegpu.com.

Requirements

• CMake
• Python3 >= 3.7
• Graphviz
• Python Packages (see requirements.txt):
  • Sphinx
  • Breathe
  • Exhale
  • sphinx_rtd_theme

Optional Requirements

• FLAMEGPU2 Source: Required for building api documentation
• Doxygen: Required for building api documentation

Installing Python Requirements

Using venv (linux)

mkdir -p -m 700 ~/.venvs
python3 -m venv ~/.venvs/FLAMEGPU2_userguide
source ~/.venvs/FLAMEGPU2_userguide/bin/activate
python3 -m pip install -Ur requirements.txt 

Using Conda (windows)

conda create --name FLAMEGPU2_userguide python=3
conda activate FLAMEGPU2_userguide
pip install -Ur requirements.txt

Building

CMake is used to generate a build script for your specific platform, this requires a supported build system.

On Linux make will normally be available, on Windows Visual Studio is the usual option, however if this is not installed Ninja is a smaller lightweight alternative.

The following command will generate build files:

mkdir -p build && cd build
cmake .. 
cmake --build .

You can optionally specify the location of the FLAMEGPU2 source repository:

mkdir -p build && cd build
cmake .. -DFLAMEGPU_ROOT="<absolute path to FLAMEGPU2>"
cmake --build .

Building the API documentation can be disabled, to improve build times via the FLAMEGPU_BUILD_API_DOCUMENTATION option set to OFF:

mkdir -p build && cd build
cmake .. -DFLAMEGPU_BUILD_API_DOCUMENTATION=OFF
cmake --build .

If you lack a build system, executing windows.bat inside the directory cmake provides an alternative. However, this still requires executing CMake if api documentation is required.

Publishing

The GitHub actions workflow publish builds the documentation from the master branch and pushes the generated html to the gh-pages branch. This is then hosted at docs.flamegpu.com.

This includes the API documentation, generated based on the contents of FLAMEGPU/FLAMEGPU2 at build time If the API has been updated but the user guide has not, the workflow can be manually triggered by users with the correct github permissions using the Run workflow button on the publish page. It may be worth manually running the build workflow first to make sure it can be built.